DCB-1534 Pickup Anywhere

References

Actions / Unknowns

Product

Technical

• Not expected.

• This would be where we intercept system-wide PUA disabled.

• Currently when moving from RESOLVED to REQUEST_PLACED_AT_SUPPLYING_AGENCY

• Polaris use ILL location - no additional handling expected

Implementation 

Preparatory work

1. DCB-1677: Add API level test for placing 3-legged requestClosed

   1. Rename existing patronRequest API test for 2-legged requests (RET-STD workflow)

   2. Add additional patronRequest tests for 3-legged requests (RET-PUA workflow)

2. DCB-1678: Add consortial config to enable or disable pickup anywhere (3-legged transaction support)Draft

   1. https://openlibraryfoundation.atlassian.net/browse/DCB-1678Default: disabled

   2. Add to DCB Admin

   3. Include data change logging

   4. Reject at preflight if necessary TBC

3. DCB-1679: Display 3-legged transaction request data inside DCB AdminOpen

   1. Extend raw local item and request status to pickup

   2. Add accordions to patron request page

Feature development

4. DCB-1680: Create request records for 3-legged transactionsDraft

   1. Introduce REQUEST_PLACED_AT_PICKUP_AGENCY

   2. Extend DCB Admin to recognise new status

   3. Update FOLIO client to (a) be workflow aware and (b) create virtual service point

   4. Defer choice of abstracting virtual entity handling

5. https://openlibraryfoundation.atlassian.net/browse/DCB-1681  

6. Extend each transition for three-legged transactions to monitor hold and item state changes

   1. https://openlibraryfoundation.atlassian.net/browse/DCB-1682

   2. https://openlibraryfoundation.atlassian.net/browse/DCB-1683

   3. https://openlibraryfoundation.atlassian.net/browse/DCB-1684

   4. https://openlibraryfoundation.atlassian.net/browse/DCB-1685

   5. DCB-1687: Extend RETURN_TRANSIT monitoring for 3-legged transactionsDraft

   6. DCB-1688: Extend COMPLETED and FINALISED transitions for 3-legged transactionsDraft

7. DCB-1689: Extend patron cancellation for 3-legged transactionsDraft

8. DCB-1690: Extend supplier cancellation for 3-legged transactionsDraft

Supplemental

9. DCB-1691: Change geographic ranking to use the pickup location rather than the borrower locationDraft

In Scope

From a user perspective the task of requesting can be broken down into

• Searching (A user activity in a discovery system like locate)

• Locating (A system activity - The process of locating the most appropriate copy of that item to try and obtain for the user)

• Requesting (A system activity - the act of placing all the relevant requests in different systems)

• Delivery (The act of getting the item to the pickup location or directly to the borrower)

• Return (Returning the item)

Pickup anywhere is relevant only to the Requesting and Return phase.

• The task is to arrange for a patron from institution a to request an item from institution b and pick it up at institution c.

• Choosing the most appropriate supplier is a separate task that comes before this stage.

• Therefore, geographic proximity is irrelevant for pickup anywhere.

It is crucial that the work needed in “DCB-Core” is independent and separate to the work needed in each adapter.

• Although all systems need to “work” there will be differences in capabilities and compliance that each host system can provide.

• The ask is to document and model these shortcomings, not to prevent implementation of a system-wide feature.

Out of scope

• Upcoming development to create and leverage preferred suppliers or automatic load balancing will not be available to pickup anywhere feature.

  • This would be a part of the locate phase anyway, and therefore logically separate to pick up anywhere.

  • Pick up anywhere is scoped to assume that the lending and borrowing libraries are already selected - its scope assumes that the locations and hosts supplied to the call “Arrange for patron from A who is a member of library B to pick up item C (Which is owned by institution D) from library E (Institution F)” are valid. It is up to steps prior to the requests process to validate those parameters.

• Special rules about which libraries can be used for pickup are out of scope. 

  • For example, a library that wishes their patrons to only pick up from their own branch libraries is out of scope. 

  • Initially, all patrons will have access to all pickup locations.

• Renewal processing and renewal blocking is out of scope for this task, but should be held in mind for later on as the same mechanism we use for the 2L path will also work for the PUA path.

• Cancelling supplier or borrower request if the pickup request cannot be successfully placed.

Detail

Configuration

Because pickup anywhere is just a new use of features already in play there is no new DCB configuration needed. 

• The detection of state changes is exactly the same as 2 legged but we are now making those calls against the pickup library as well as the borrowing library.

• The main work happens when we detect these state changes - the response procedures are different when the PUA workflow is in force to the standard 2L workflow.

• Individual libraries can’t opt out of pickup anywhere. There is no need to provide configuration support for this. 

Locate

• Will need to change to show all available pickup locations

• Extensions to tracking code for PUA workflows may be needed to watch the state of the PUA-item and the PUA hold.

Requesting flow

The system enters the requesting flow with lending, borrowing and pickup locations already identified, and hence knows if this is a “3-Legged” transaction. The PUA case is already identified and clearly flagged to the workflow engine.

DCB Service 

Extend automated tests to mock and be able to demonstrate 3-legged request placement. 

The workflow engine needs to apply a different requesting flow to the normal 2-legged transaction:

1. Attempt to place the hold at the lending institution - with delivery to the pickup institution.

   1. Lookup or Create the virtual patron

   2. Place the hold on the item

   3. If requesting fails at this point, clean up any records and exit to whatever outer control loop exits the process or tries re-request.

2. Create the borrower virtual item and hold

   1. Create a virtual item for the loan

   2. Create a hold for the loan

   3. Additional for FOLIO: 

      1. change role (from `borrower_pickup` to `borrower`) 

      2. point to VIRTUAL(?) service point  

      3. changes to mod-dcb? TBC

3. Place the PUA hold (this would be a noop on 2-legged)

   1. Create a virtual item (And set all it’s tracking details in the patron request object)

   2. Create a virtual patron (And set it’s details in the patron request object)

   3. Create a hold on the virtual item for the virtual patron so that when the item arrives staff know which pick up shelf to route the item to.

If we can’t place PUA request: 

• Terminate the request in ERROR, indicating what step of pickup request creation has failed

At the end of this step

• A virtual item with the correctly mapped item type exists in the borrowing and pickup systems

• A virtual patron exists in the lending and pickup systems with the correctly mapped patron type

• A hold exists in both the patron home and pickup systems with the correct pickup location code. 

DCB Admin

• Add Pickup Location request details to patron request

Tracking (Delivery to pickup)

The system now needs to watch the supplying library state as it does for 2 legged transactions. We are looking for the In-Transit state. Upon detection a PUA reaction needs to happen - this is different to the standard 2 legged action. Because PUA is clearly identified as the “Requesting workflow” we need to invoke a different procedure in response to the in transit to pickup state.

1. Perform “Update Borrower Request - in transit” on the borrower system - Update the state on the patron system vitem (So the patron knows that the item is en-route)

2. Perform “Update Borrower Request - in transit” on the pick up system - Update the state on the pickup vitem so that staff at the pickup library know that the item is en-route.

At the end of this step

• The hold/item in the borrower and pickup systems have been updated to in transit

Tracking (Received at pickup)

As with 2 legged the system needs to watch for the arrival of the item - but this time at the pickup location. The system should use the same tracking mechanisms as for 2-legged but based on the pickup item and hold data in the patron request.

When the system detects that the item is received at the pickup location

1. Call “Update supplier request - received at pickup” to ask the suppliers home system to do whatever it needs to record that the item has arrived at the pickup location.

2. Call the “update borrower request - received at pickup” on the patrons home system - so that the patron can see on their own library record that the item has been received.

At the end of this step

• The hold in the pickup system has been updated to received at pickup by the pickup system

• DCB has updated the hold in the lending and borrowing systems to indicate that the item is received at pickup

Tracking (Ready for pickup)

As with 2 legged the system needs to watch for the arrival of the item - but this time at the pickup location. The system should use the same tracking mechanisms as for 2-legged but based on the pickup item and hold data in the patron request.

When the system detects that the item is ready for pickup at the pickup location

1. Call “Update supplier request - ready for pickup” to ask the suppliers home system to do whatever it needs to record that the item has arrived at the pickup location.

2. Call the “update borrower request - ready for pickup” on the patrons home system - so that the patron can see on their own library record that the item is ready to be picked up.

At the end of this step

• The hold in the pickup system has been updated to on hold shelf by the pickup system

• DCB has updated the hold in the lending and borrowing systems to indicate that the item is ready for pick up

Tracking (Loaned)

DCB needs to watch the status of the hold/loan at the pickup system for a LOANED status. When it detects, because the workflow in force is PUA invoke a different response procedure:

1. Update the lending system as per standard 2 legged loan

2. Update the patron home system - check out the item to the patron, filling the hold on the patron home system.

At the end of this step

• The supplying system has its item status updated to loaned

• The patron status has the virtual item checked out to the real patron - filling the hold on the patron home system

Tracking (Returned)

DCB now needs to watch two systems - the patron home system and the pickup anywhere system - in either system an item state of “AVAILABLE” (Or whatever the current state of the art is for determining returned items in standard 2 legged) triggers the returned flow.

1. If the item was returned to EITHER the patrons home system or the pickup location system updated the supplier system with the same “In transit” state used for the 2 legged return step.

At the end of this step:

• The supplying system item is updated to be in-transit

Tracking (Complete)

Same with standard 2 legged - detection of completed but when PUA workflow is in place run a different complete procedure:

1. Final Clean up the borrower system

2. Final Clean up of the pickup system (Remove virtual item, virtual bib)

Patron Cancellation

Detection of Cancellation up to in-transit to pickup location is as per 2 legged, but the process invoked in reaction to that event is different in PUA:

1. Clean up borrower system

2. Clean up pickup system

At the end of this step:

• Borrower and Pickup systems are cleaned

• Item is available for loan

Library Cancellation

• Supplier cancellation 

  • detection as per existing supplier cancellation 

  • reaction: 

    • cancel at borrowing and pickup library