Holds Rewrite RFC

From Koha Wiki

Jump to: navigation, search
Koha > Technical > Development > RFCs
Koha > Technical > Development > RFCs > Koha components for RFCs > Library System Modules RFCs > Circulation RFCs


Holds Rewrite RFC

Status: unknown
Sponsored by: RHCL and OSOL
Developed by: ByWater Solutions and Catalyst
Expected for: Unsure
Bug number: Bug 5609
Work in progress repository: No URL given.
Description: ===Placing Holds===

Holds pick up location

The system shall include a system preference to toggle whether to allow users to choose their hold pick up branch. If disabled, they can only pick up from their home library.

Multiple holds per title

Users shall be able to place holds on multiple items attached to a single biblio, subject to two circulation policies (configurable on the branch/item type/patron category level). One policy shall indicate the number of holds that can be placed on items with different enumchron values (different volumes), while another shall indicate the number of holds that can be placed on items with the same enumchron field (different copies). This will allow libraries to allow patrons to place holds on multiple volumes of a title, up to a reasonable limit, while limiting or preventing multiple holds on 'equivalent' copies.

Holds Policy Preferences Moved to Circ Matrix

The AllowOnShelfHolds system preference shall be moved to the Circulation Matrix.

The OPACItemHolds system preference shall be moved to the Circulation Matrix.

The ReservesMaxPickupDelay system preference shall be moved to the Circulation Matrix.

Holds Queue management

More stable queue structure

The holds queue is currently very fragile. It is very easy for two holds to be assigned the same priority, or for there to be gaps in the priority sequence.

The holds system should provide a stable mechanism for ordering holds. Holds placed simultaneously on the same title from two different work stations shall not be assigned the same priority level.

Further, There is currently no unique identifier for a hold. It is possible for two indistinguishable holds from being placed into the system, which makes filling and deletion difficult.

The holds system should have a unique identifier for each hold in the system.

Idea: bi-directional linked list data structure, i.e. each hold points to the one ahead of it and the one behind it.

Clear statuses

For each hold in the system, there should be a clear, single status to describe it's current state. These statuses should include:

  • Waiting (in holds queue)
  • Ready to pull
  • Pulled and awaiting pickup
  • Filled
  • Expired
  • Long waiting
  • In transit
  • Suspended
  • Canceled

Since these statuses have concrete system states attached to them, they must be hard coded into the system. The use of an Authorized Value list would not be sufficient.

Status Workflow

Not every status should be reachable from either other status. Below is a mapping of which statuses a hold shall be able change between. O with a green background indicates possible, while X with a red background indicates impossible. Grey cells are for self-references.


Holds shall be considered 'waiting in queue' until they reach the top position of the queue, at which time they change to 'ready to pull'. While in the queue, they can expire, be suspended, or be canceled.

Once the hold is ready to pull, the next natural next step for the hold to transition to the “Pulled” state, where it awaits being picked up by the patron. Since this status just means the hold is at the top of the queue, if the queue is rearranged, the status of the hold could go back to 'Waiting in queue'. The hold can also expire, be suspended or be canceled.

After the hold is pulled, it should either be picked up by the patron and marked as 'filled', or put 'in transit' to the pick up location. It can also still expire or be canceled. If the hold waits to be picked up for more than appropriate MaxReservePickupDelay circ rule, it will be marked as 'long waiting'.

If a hold needs to be transferred to another branch, the status shall go from 'Ready to Pull' to 'In Transit'. Once the item arrives at it's destination and is received, it shall be marked as 'Pulled and ready for pickup'

Expired, Suspended and Canceled holds can be brought back into the queue. “Filled” is a terminal status; the hold record can now be archived.

Automatic Cancellation of Holds Long Waiting

A system preference shall be added to determine if Long Waiting holds are automatically canceled, suspended, or left to be dealt with manually. Suspension of holds

Users should be able to place a hold 'on suspension'. This means the hold will preserve it's place in the queue, but it will be skipped over to the next non-suspended hold when the item becomes available. Upon un-suspension, the hold will resume it's original place in the queue.

There shall be a button to suspend all holds for a user at once, both in the staff client and the OPAC (if OPAC holds management is enabled)

Auto unsuspend holds by date

For users who know the date when they will be able to receive holds again, there shall be an available box to specify this date at suspension time. When that date rolls around, the hold will be automatically resumed. This box shall also be available when suspending multiple holds at once. This box shall be available in the staff client, and in the OPAC (if OPAC holds management is enabled).

The use of this features shall be toggleable by a system preference.

A single 'Holds Report'

Koha currently has two holds reports: Holds to Pull and Holds Queue. The difference between them is often unclear and confusing. The system shall provide a single report page to detail which materials should be pulled from a branches shelves, and where these items should be sent.

Filling Holds

Transport Cost Matrix

The system shall contain a new administrative page that serves to manage the relative costs of transporting an item between branches. “Cost” does not directly correspond to currency, but rather is a measurement of the difficulty of transporting the item between the two branches.

For each branch, it shall be possible to specify a numeric value indicating the 'cost' of transporting the item from that branch to every other branch. A toggle shall also be available to block all transport from any branch to any other branch. The toggle shall not change the 'cost' value associated with the transport between any two branches.

Filling Holds using the Transport Cost Matrix

A system preference shall be added to control whether holds are filled using the Transport Cost Matrix, or not.

If the system is configured to use the Transport Cost Matrix for filling holds, then when attempting to fill a hold, the system will search for the lowest cost branch, and attempt to fill the hold with an item from that branch first. Branches of equal cost shall be selected from randomly. The branch or branches of the next highest cost shall be selected from only if all the branches in the previous group are unable to fill the hold.

The system shall use the item's current holding branch when determining whether the item can fulfill a hold using the Transport Cost Matrix. This behaviour shall be overruled if the AutomaticItemReturn system preference is enabled.

Hold queue 'jump'

A setting should be configurable which permits the library to establish a point in the holds queue when a patron may get a copy of the item requested because it has been returned to their specified pick-up location even if they are not the top name on the holds queue.

Use case: Many libraries are spending hundreds of thousands of dollars moving material between libraries so a balance needs to be found between what is fair to patrons and what is economically manageable for libraries. If a patron is number 30 in a queue of 100 people waiting for the newest Harry Potter and a copy is returned to that patron’s pick-up location, the patron doesn’t get it. The item will only be made available to the person specified as #1 on the holds list. This seems fair. But what if that patron was #5 on the list, would it be reasonable to save the library money in delivery and let the #5 patron have it? This is the idea behind allowing libraries to specify a setting which would permit a patron to get the next copy that becomes available at their pick-up location. Each library needs to be able to figure out what they can justify. Some will want to say, you can jump the queue if you item is returned to your pick up location as long as you are in the top 10, others might say you have to be the top 2 or 3.

Personal tools