Support SIP checkin 'cancel' operation (BI field)

[Bill Erickson]

Evergreen 3.5 / Wishlist

SIP supports a "cancel" operation on checkin (and checkout) requests via the "BI" SIP field. The purpose of this field is in effect to undo a checkout or checkin operation.

The use case driving checkin+cancel is handling error conditions with 3rd-party book lockers.

1. Patron authenticates with locker via SIP2
2. Locker checks items out to patron, fulfilling holds, etc. via SIP2.
3. Locker door fails to open or other error condition occurs.
4. Locker sends checkin+cancel request via SIP2 to undo the checkout from step 2.

The cancel operation should check the item in -- presumably a no-op checkin -- and return any fulfilled holds to their previously captured, but unfulfilled state.

I suspect there are unforeseen complexities with this. Thoughts appreciated.

SIPServer.pm already supports this field, so code changes only need to be made to the Evergreen SIP code.

[Bill Erickson (berick)]

Here's a branch:

https://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/berick/lp1893968-sip-checkin-with-cancel

In the interest of narrowing the scope, instead of a full rollback option, I have implemented a new flag for the open-ils.circ.checkin API called "revert_hold_fulfillment", since this is the specific behavior I'm interested in.

It behaves like a No-Op checkin, with the addition that if a hold was fulfilled by the checked out item for the patron which circulated the item, the hold fulfillment is rolled back and the item is put back on the holds shelf.

Teaches the SIP Checkin code to pass the 'revert_hold_fulfillment' flag to its checkin call when the SIP 'cancel' value is set, i.e. the SIP 'BI' field contains a 'Y' value.

To test without SIP, check an item out to patron which fulfills a hold. Then in srfsh:

srfsh% request open-ils.circ open-ils.circ.checkin "<AUTHTOKEN>" {"copy_barcode":"<COPY_BARCODE", "revert_hold_fulfillment":1}

Confirm the hold in question has been un-fulfilled and the item in question is now back on the holds shelf.

[Mike Rylander (mrylander)]

I think you're definitely right about unforeseen complexities. :)

My first questions:

 * How long into the future is the "revert" expected to be possible? As in, is this intended to be used /immediately/ after an incorrect checkin/checkout, during the same SIP patron session? Or should you be able to claw back the checkin/checkout/hold-capture until the state of the copy changes again?
 * What about transits?
 * What about fine finalization on checkin?

... I'll probably have more questions after I have a chance to look at the code, so thanks for sharing right away!

[Bill Erickson (berick)]

Hey, thanks Mike.

I. I considered a YAOUS to limit the time range for reverting. The use case is a checkout followed almost immediately by a revert checkin.

II. Transits shouldn't come into it. The checkin acts as a no-op plus hold revert, and revert is only possible if the item status is checked out. Upon completion, the item status goes back to on-holds-shelf.

III. Since the use case calls for quick returns, I was thinking fines would not come into it, but I agree that needs to be locked down one way or the other.