1 package C4::HoldsQueue;
3 # Copyright 2011 Catalyst IT
5 # This file is part of Koha.
7 # Koha is free software; you can redistribute it and/or modify it
8 # under the terms of the GNU General Public License as published by
9 # the Free Software Foundation; either version 3 of the License, or
10 # (at your option) any later version.
12 # Koha is distributed in the hope that it will be useful, but
13 # WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 # GNU General Public License for more details.
17 # You should have received a copy of the GNU General Public License
18 # along with Koha; if not, see <http://www.gnu.org/licenses>.
20 # FIXME: expand perldoc, explain intended logic
26 use C4::Circulation qw( GetBranchItemRule );
27 use Koha::DateUtils qw( dt_from_string );
28 use Koha::Hold::HoldsQueueItems;
34 use List::Util qw( shuffle );
35 use List::MoreUtils qw( any );
36 use Algorithm::Munkres qw();
38 our (@ISA, @EXPORT_OK);
47 UpdateTransportCostMatrix
48 GetPendingHoldRequestsForBib
49 load_branches_to_pull_from
50 update_queue_for_biblio
57 =head2 TransportCostMatrix
59 TransportCostMatrix();
61 Returns Transport Cost Matrix as a hashref <to branch code> => <from branch code> => cost
65 sub TransportCostMatrix {
68 my $dbh = C4::Context->dbh;
69 my $transport_costs = $dbh->selectall_arrayref("SELECT * FROM transport_cost",{ Slice => {} });
71 my $today = dt_from_string();
72 my %transport_cost_matrix;
73 foreach (@$transport_costs) {
74 my $from = $_->{frombranch};
75 my $to = $_->{tobranch};
76 my $cost = $_->{cost};
77 my $disabled = $_->{disable_transfer};
78 $transport_cost_matrix{$to}{$from} = {
80 disable_transfer => $disabled
84 return \%transport_cost_matrix;
87 =head2 UpdateTransportCostMatrix
89 UpdateTransportCostMatrix($records);
91 Updates full Transport Cost Matrix table. $records is an arrayref of records.
92 Records: { frombranch => <code>, tobranch => <code>, cost => <figure>, disable_transfer => <0,1> }
96 sub UpdateTransportCostMatrix {
98 my $dbh = C4::Context->dbh;
100 my $sth = $dbh->prepare("INSERT INTO transport_cost (frombranch, tobranch, cost, disable_transfer) VALUES (?, ?, ?, ?)");
102 $dbh->do("DELETE FROM transport_cost");
103 foreach (@$records) {
104 my $cost = $_->{cost};
105 my $from = $_->{frombranch};
106 my $to = $_->{tobranch};
107 if ($_->{disable_transfer}) {
110 elsif ( !defined ($cost) || ($cost !~ m/(0|[1-9][0-9]*)(\.[0-9]*)?/o) ) {
111 warn "Invalid $from -> $to cost $cost - must be a number >= 0, disabling";
113 $_->{disable_transfer} = 1;
115 $sth->execute( $from, $to, $cost, $_->{disable_transfer} ? 1 : 0 );
119 =head2 GetHoldsQueueItems
121 GetHoldsQueueItems({ branchlimit => $branch, itemtypeslimit => $itype, ccodeslimit => $ccode, locationslimit => $location );
123 Returns hold queue for a holding branch. If branch is omitted, then whole queue is returned
127 sub GetHoldsQueueItems {
129 my $dbh = C4::Context->dbh;
132 $search_params->{'me.holdingbranch'} = $params->{branchlimit} if $params->{branchlimit};
133 $search_params->{'itype'} = $params->{itemtypeslimit} if $params->{itemtypeslimit};
134 $search_params->{'ccode'} = $params->{ccodeslimit} if $params->{ccodeslimit};
135 $search_params->{'location'} = $params->{locationslimit} if $params->{locationslimit};
137 my $results = Koha::Hold::HoldsQueueItems->search(
148 'item_group_item' => 'item_group'
153 'ccode', 'location', 'item.cn_sort', 'author',
154 'biblio.title', 'pickbranch', 'reservedate'
166 Top level function that turns reserves into tmp_holdsqueue and hold_fill_targets.
172 my $unallocated = $params->{unallocated};
173 my $dbh = C4::Context->dbh;
175 unless ($unallocated) {
176 $dbh->do("DELETE FROM tmp_holdsqueue"); # clear the old table for new info
177 $dbh->do("DELETE FROM hold_fill_targets");
181 my $total_requests = 0;
182 my $total_available_items = 0;
183 my $num_items_mapped = 0;
186 my $transport_cost_matrix;
187 my $use_transport_cost_matrix = C4::Context->preference("UseTransportCostMatrix");
188 if ($use_transport_cost_matrix) {
189 $transport_cost_matrix = TransportCostMatrix();
190 unless (keys %$transport_cost_matrix) {
191 warn "UseTransportCostMatrix set to yes, but matrix not populated";
192 undef $transport_cost_matrix;
196 $branches_to_use = load_branches_to_pull_from($use_transport_cost_matrix);
198 my $bibs_with_pending_requests = GetBibsWithPendingHoldRequests();
200 foreach my $biblionumber (@$bibs_with_pending_requests) {
204 my $result = update_queue_for_biblio(
206 biblio_id => $biblionumber,
207 branches_to_use => $branches_to_use,
208 transport_cost_matrix => $transport_cost_matrix,
209 unallocated => $unallocated
213 $total_requests += $result->{requests};
214 $total_available_items += $result->{available_items};
215 $num_items_mapped += $result->{mapped_items};
219 =head2 GetBibsWithPendingHoldRequests
221 my $biblionumber_aref = GetBibsWithPendingHoldRequests();
223 Return an arrayref of the biblionumbers of all bibs
224 that have one or more unfilled hold requests.
228 sub GetBibsWithPendingHoldRequests {
229 my $dbh = C4::Context->dbh;
231 my $bib_query = "SELECT DISTINCT biblionumber
235 AND reservedate <= CURRENT_DATE()
237 AND reserve_id NOT IN (SELECT reserve_id FROM hold_fill_targets)
239 my $sth = $dbh->prepare($bib_query);
242 my $biblionumbers = $sth->fetchall_arrayref();
244 return [ map { $_->[0] } @$biblionumbers ];
247 =head2 GetPendingHoldRequestsForBib
249 my $requests = GetPendingHoldRequestsForBib( { biblionumber => $biblionumber, unallocated => $unallocated } );
251 Returns an arrayref of hashrefs to pending, unfilled hold requests
252 on the bib identified by $biblionumber. Optionally returns only unallocated holds. The following keys
253 are present in each hashref:
264 The arrayref is sorted in order of increasing priority.
268 sub GetPendingHoldRequestsForBib {
270 my $biblionumber = $params->{biblionumber};
271 my $unallocated = $params->{unallocated};
273 my $dbh = C4::Context->dbh;
275 my $request_query = "SELECT biblionumber, borrowernumber, itemnumber, priority, reserve_id, reserves.branchcode,
276 reservedate, reservenotes, borrowers.branchcode AS borrowerbranch, itemtype, item_level_hold, item_group_id
278 JOIN borrowers USING (borrowernumber)
279 WHERE biblionumber = ?
282 AND reservedate <= CURRENT_DATE()
284 $request_query .= "AND reserve_id NOT IN (SELECT reserve_id FROM hold_fill_targets) " if $unallocated;
285 $request_query .= "ORDER BY priority";
286 my $sth = $dbh->prepare($request_query);
287 $sth->execute($biblionumber);
289 my $requests = $sth->fetchall_arrayref({});
294 =head2 GetItemsAvailableToFillHoldRequestsForBib
296 my $available_items = GetItemsAvailableToFillHoldRequestsForBib($biblionumber, $branches_ar);
298 Returns an arrayref of items available to fill hold requests
299 for the bib identified by C<$biblionumber>. An item is available
300 to fill a hold request if and only if:
303 * it is not withdrawn
304 * it is not marked notforloan
305 * it is not currently in transit
307 * it is not sitting on the hold shelf
308 * it is not damaged (unless AllowHoldsOnDamagedItems is on)
312 sub GetItemsAvailableToFillHoldRequestsForBib {
313 my ($biblionumber, $branches_to_use) = @_;
315 my $dbh = C4::Context->dbh;
316 my $items_query = "SELECT items.itemnumber, homebranch, holdingbranch, itemtypes.itemtype AS itype
319 if ( C4::Context->preference('item-level_itypes') ) {
320 $items_query .= "LEFT JOIN itemtypes ON (itemtypes.itemtype = items.itype) ";
322 $items_query .= "JOIN biblioitems USING (biblioitemnumber)
323 LEFT JOIN itemtypes USING (itemtype) ";
325 $items_query .= " LEFT JOIN branchtransfers ON (
326 items.itemnumber = branchtransfers.itemnumber
327 AND branchtransfers.datearrived IS NULL AND branchtransfers.datecancelled IS NULL
329 $items_query .= " WHERE items.notforloan = 0
330 AND holdingbranch IS NOT NULL
333 $items_query .= " AND damaged = 0" unless C4::Context->preference('AllowHoldsOnDamagedItems');
334 $items_query .= " AND items.onloan IS NULL
335 AND (itemtypes.notforloan IS NULL OR itemtypes.notforloan = 0)
336 AND items.itemnumber NOT IN (
339 WHERE biblionumber = ?
340 AND itemnumber IS NOT NULL
341 AND (found IS NOT NULL OR priority = 0)
343 AND items.itemnumber NOT IN (
346 WHERE biblionumber = ?
348 AND items.biblionumber = ?
349 AND branchtransfers.itemnumber IS NULL";
351 my @params = ($biblionumber, $biblionumber, $biblionumber);
352 if ($branches_to_use && @$branches_to_use) {
353 $items_query .= " AND holdingbranch IN (" . join (",", map { "?" } @$branches_to_use) . ")";
354 push @params, @$branches_to_use;
356 my $sth = $dbh->prepare($items_query);
357 $sth->execute(@params);
359 my $itm = $sth->fetchall_arrayref({});
361 my $rule = C4::Circulation::GetBranchItemRule($_->{homebranch}, $_->{itype});
362 $_->{holdallowed} = $rule->{holdallowed};
363 $_->{hold_fulfillment_policy} = $rule->{hold_fulfillment_policy};
367 =head2 _checkHoldPolicy
369 _checkHoldPolicy($item, $request)
371 check if item agrees with hold policies
375 sub _checkHoldPolicy {
376 my ( $item, $request ) = @_;
378 return 0 unless $item->{holdallowed} ne 'not_allowed';
381 if $item->{holdallowed} eq 'from_home_library'
382 && $item->{homebranch} ne $request->{borrowerbranch};
385 if $item->{'holdallowed'} eq 'from_local_hold_group'
386 && !Koha::Libraries->find( $item->{homebranch} )
387 ->validate_hold_sibling( { branchcode => $request->{borrowerbranch} } );
389 my $hold_fulfillment_policy = $item->{hold_fulfillment_policy};
392 if $hold_fulfillment_policy eq 'holdgroup'
393 && !Koha::Libraries->find( $item->{homebranch} )
394 ->validate_hold_sibling( { branchcode => $request->{branchcode} } );
397 if $hold_fulfillment_policy eq 'homebranch'
398 && $request->{branchcode} ne $item->{$hold_fulfillment_policy};
401 if $hold_fulfillment_policy eq 'holdingbranch'
402 && $request->{branchcode} ne $item->{$hold_fulfillment_policy};
405 if $hold_fulfillment_policy eq 'patrongroup'
406 && !Koha::Libraries->find( $request->{borrowerbranch} )
407 ->validate_hold_sibling( { branchcode => $request->{branchcode} } );
413 sub _allocateWithTransportCostMatrix {
415 $hold_requests, $available_items, $branches_to_use, $libraries, $transport_cost_matrix, $allocated_items,
421 my @remaining_items = grep { !exists $allocated_items->{ $_->{itemnumber} } && $_->{holdallowed} ne 'not_allowed'; }
424 my @requests = grep { !defined $_->{itemnumber} } @$hold_requests;
427 my $num_agents = scalar(@remaining_items);
428 my $num_tasks = scalar(@requests);
430 return [] if $num_agents == 0 || $num_tasks == 0;
432 if ( $num_tasks > $num_agents ) {
433 @remaining = @requests[ $num_agents .. $num_tasks - 1 ];
434 @requests = @requests[ 0 .. $num_agents - 1 ];
435 $num_tasks = $num_agents;
438 my @m = map { [ (undef) x $num_tasks ] } ( 1 .. $num_agents );
440 my $inf = -1; # Initially represent infinity with a negative value.
443 # If some candidate holds requests cannot be filled and there are
444 # hold requests remaining, we will try again a limited number of
447 # The limit is chosen arbitrarily and only servers to keep the
448 # asymptotic worst case to O(num_tasks³).
450 my $retries = $RETRIES;
452 my @candidate_tasks = ( (0) x $num_tasks );
453 my @candidate_agents = ( (0) x $num_agents );
457 return [] if $num_agents == 0 || $num_tasks == 0;
459 if ( $num_tasks < $num_agents && @remaining ) {
461 # On retry, move tasks from @remaining to @requests up to
462 # the number of agents.
463 my $nr = scalar(@remaining);
464 my $na = $num_agents - $num_tasks;
465 my $nm = $nr < $na ? $nr : $na;
466 push @requests, ( splice @remaining, 0, $nm );
468 for ( my $t = scalar(@candidate_tasks) ; $t < $num_tasks ; $t++ ) {
469 push @candidate_tasks, 0;
473 for ( my $i = 0 ; $i < $num_agents ; $i++ ) {
474 for ( my $j = $r ; $j < $num_tasks ; $j++ ) {
475 my $item = $remaining_items[$i];
476 my $request = $requests[$j];
478 my $pickup_branch = $request->{branchcode} || $request->{borrowerbranch};
479 my $srcbranch = $item->{holdingbranch};
483 unless _checkHoldPolicy( $item, $request );
486 unless $items_by_itemnumber->{ $item->{itemnumber} }->{_object}
487 ->can_be_transferred( { to => $libraries->{ $request->{branchcode} } } );
489 # If hold itemtype is set, item's itemtype must match
492 unless ( !$request->{itemtype}
493 || $item->{itype} eq $request->{itemtype} );
495 # If hold item_group is set, item's item_group must match
499 !$request->{item_group_id}
500 || ( $item->{_object}->item_group
501 && $item->{_object}->item_group->id eq $request->{item_group_id} )
504 my $cell = $transport_cost_matrix->{$pickup_branch}{$srcbranch};
507 if ( !defined $cell && $pickup_branch eq $srcbranch ) {
509 } elsif ( !defined $cell || $cell->{disable_transfer} ) {
512 if ( defined $cell->{cost} ) {
513 $cost = $cell->{cost};
521 if ( $cost != $inf ) {
523 # There is at least one possible item in row $i and column $j
524 $candidate_tasks[$j] = 1;
525 $candidate_agents[$i] = 1;
528 if ( $cost > $max ) {
534 # Remove any hold request for which there is no finite transport cost item available.
535 my $removed_something = 0;
537 for ( my $j = 0, my $j0 = 0 ; $j < $num_tasks ; $j++ ) {
538 if ( !$candidate_tasks[$j] ) {
539 for ( my $i = 0 ; $i < $num_agents ; $i++ ) {
540 splice @{ $m[$i] }, $j - $j0, 1;
542 splice @requests, $j - $j0, 1;
544 $removed_something = 1;
548 $num_tasks = scalar(@requests);
550 if ( $num_agents > $num_tasks && @remaining ) {
553 @candidate_tasks = ( (1) x $num_tasks );
554 @candidate_agents = ( (1) x $num_agents );
558 if ( $num_tasks > $num_agents ) {
560 return [] if $num_agents == 0;
561 unshift @remaining, ( splice @requests, $num_agents );
562 $num_tasks = $num_agents;
565 return [] if $num_agents == 0 || $num_tasks == 0;
567 # Substitute infinity with a cost that is higher than the total of
568 # any possible assignment. This ensures that any possible
569 # assignment will be selected before any assignment of infinite
570 # cost. Infinite cost assignments can be be filtered out at the
572 $inf = $max * $num_tasks + 1;
574 my @m0 = map {[(undef) x $num_tasks]} (1..$num_agents);
575 for ( my $i = 0 ; $i < $num_agents ; $i++ ) {
576 for ( my $j = 0 ; $j < $num_tasks ; $j++ ) {
577 if ( $m[$i][$j] < 0 ) {
578 # Bias towards not allocating items to holds closer to
579 # the end of the queue in the queue if not all holds
580 # can be filled by representing infinity with
582 $m0[$i][$j] = $inf + ( $num_tasks - $j );
584 $m0[$i][$j] = $m[$i][$j];
589 my $res = [ (undef) x $num_agents ];
591 Algorithm::Munkres::assign( \@m0, $res );
593 my @unallocated = ();
595 for ( my $i = 0 ; $i < $num_agents ; $i++ ) {
597 if ( !defined $j || $j >= $num_tasks ) {
599 # If the algorithm zero-pads the matrix
600 # (Algorithm::Munkres version 0.08) holds may be
601 # allocated to nonexisting items ($j >= 0). We just ignore these.
604 if ( $m0[$i][$j] > $max ) {
606 # No finite cost item was assigned to this hold.
607 push @unallocated, $j;
610 my $request = $requests[$j];
611 my $item = $remaining_items[$i];
615 borrowernumber => $request->{borrowernumber},
616 biblionumber => $request->{biblionumber},
617 holdingbranch => $item->{holdingbranch},
618 pickup_branch => $request->{branchcode}
619 || $request->{borrowerbranch},
620 reserve_id => $request->{reserve_id},
621 item_level => $request->{item_level_hold},
622 reservedate => $request->{reservedate},
623 reservenotes => $request->{reservenotes},
629 if ( $retries-- > 0 && @unallocated && @remaining ) {
631 # Remove the transport cost of unfilled holds and compact the matrix.
632 # Also remove the hold request from the array.
633 for ( my $i = 0 ; $i < $num_agents ; $i++ ) {
635 for ( my $j = 0 ; $j < $num_tasks ; $j++ ) {
636 if ( $u < scalar(@unallocated) && $unallocated[$u] == $j ) {
639 $m[$i][ $j - $u ] = $m[$i][$j];
643 for ( my $u = 0 ; $u < scalar(@unallocated) ; $u++ ) {
644 splice @requests, $unallocated[$u], 1;
646 $num_tasks = scalar(@requests);
650 if ( $retries == 0 && @unallocated && @remaining ) {
651 Koha::Logger->get->warn(
652 "There are available items that have not been allocated and remaining holds, but we abort trying to fill these after $RETRIES retries."
662 =head2 MapItemsToHoldRequests
664 my $item_map = MapItemsToHoldRequests($hold_requests, $available_items, $branches, $transport_cost_matrix)
667 $hold_requests is a hash containing hold information built by GetPendingHoldRequestsForBib
668 $available_items is a hash containing item information built by GetItemsAvailableToFillHoldRequestsForBib
669 $branches is an arrayref to a list of branches filled by load_branches_to_pull_from
670 $transport_cost_matrix is a hash of hashes with branchcodes as keys, listing the cost to transfer from that branch to another
672 Returns a hash of hashes with itemnumbers as keys, each itemnumber containing a hash with the information
673 about the hold it has been mapped to.
675 This routine attempts to match the holds in the following priority
676 1 - If local holds priority is enabled we check all requests to see if local matches can be found
677 2 - We check for item level matches and fill those
678 3 - We now loop the remaining requests in priority order attempting to fill with
679 a - Items where HoldsQueuePrioritizeBranch matches either from items held at the pickup branch, or at the least cost branch (if Transport Cost Matrix is being used)
680 b - Items where the homebranch of the item and the pickup library match
681 c - Items from the least cost branch (or items at the pickup location if available)
682 d - Any item that can fill the hold
686 sub MapItemsToHoldRequests {
687 my ($hold_requests, $available_items, $branches_to_use, $transport_cost_matrix) = @_;
689 # handle trival cases
690 return unless scalar(@$hold_requests) > 0;
691 return unless scalar(@$available_items) > 0;
693 map { $_->{_object} = Koha::Items->find( $_->{itemnumber} ) } @$available_items;
695 map { $libraries->{$_->id} = $_ } Koha::Libraries->search->as_list;
697 # group available items by itemnumber
698 my %items_by_itemnumber = map { $_->{itemnumber} => $_ } @$available_items;
700 # items already allocated
701 my %allocated_items = ();
703 # map of items to hold requests
706 # figure out which item-level requests can be filled
707 my $num_items_remaining = scalar(@$available_items);
709 # Look for Local Holds Priority matches first
710 if ( C4::Context->preference('LocalHoldsPriority') ) {
711 my $LocalHoldsPriorityPatronControl =
712 C4::Context->preference('LocalHoldsPriorityPatronControl');
713 my $LocalHoldsPriorityItemControl =
714 C4::Context->preference('LocalHoldsPriorityItemControl');
716 foreach my $request (@$hold_requests) {
717 last if $num_items_remaining == 0;
718 my $patron = Koha::Patrons->find($request->{borrowernumber});
719 next if $patron->category->exclude_from_local_holds_priority;
721 my $local_hold_match;
722 foreach my $item (@$available_items) {
723 next if $item->{_object}->exclude_from_local_holds_priority;
725 next unless _can_item_fill_request( $item, $request, $libraries );
727 next if $request->{itemnumber} && $request->{itemnumber} != $item->{itemnumber};
729 my $local_holds_priority_item_branchcode =
730 $item->{$LocalHoldsPriorityItemControl};
732 my $local_holds_priority_patron_branchcode =
733 ( $LocalHoldsPriorityPatronControl eq 'PickupLibrary' )
734 ? $request->{branchcode}
735 : ( $LocalHoldsPriorityPatronControl eq 'HomeLibrary' )
736 ? $request->{borrowerbranch}
740 $local_holds_priority_item_branchcode eq
741 $local_holds_priority_patron_branchcode;
743 if ($local_hold_match) {
744 if ( exists $items_by_itemnumber{ $item->{itemnumber} }
745 and not exists $allocated_items{ $item->{itemnumber} }
746 and not $request->{allocated})
748 $item_map{ $item->{itemnumber} } = {
749 borrowernumber => $request->{borrowernumber},
750 biblionumber => $request->{biblionumber},
751 holdingbranch => $item->{holdingbranch},
752 pickup_branch => $request->{branchcode}
753 || $request->{borrowerbranch},
754 reserve_id => $request->{reserve_id},
755 item_level => $request->{item_level_hold},
756 reservedate => $request->{reservedate},
757 reservenotes => $request->{reservenotes},
759 $allocated_items{ $item->{itemnumber} }++;
760 $request->{allocated} = 1;
761 $num_items_remaining--;
768 # Handle item level requests
769 # Note that we loop the requests in priority order reserving an item for each title level hold
770 # So we will only fill item level requests if there are enough items to fill higher priority
772 foreach my $request (@$hold_requests) {
773 last if $num_items_remaining == 0;
774 next if $request->{allocated};
776 # is this an item-level request?
777 if (defined($request->{itemnumber})) {
778 # fill it if possible; if not skip it
779 if ( exists $items_by_itemnumber{ $request->{itemnumber} }
780 and not exists $allocated_items{ $request->{itemnumber} }
781 and _can_item_fill_request( $items_by_itemnumber{ $request->{itemnumber} }, $request, $libraries ) )
784 $item_map{ $request->{itemnumber} } = {
785 borrowernumber => $request->{borrowernumber},
786 biblionumber => $request->{biblionumber},
787 holdingbranch => $items_by_itemnumber{ $request->{itemnumber} }->{holdingbranch},
788 pickup_branch => $request->{branchcode} || $request->{borrowerbranch},
789 reserve_id => $request->{reserve_id},
790 item_level => $request->{item_level_hold},
791 reservedate => $request->{reservedate},
792 reservenotes => $request->{reservenotes},
794 $allocated_items{ $request->{itemnumber} }++;
795 $num_items_remaining--;
798 # it's title-level request that will take up one item
799 $num_items_remaining--;
803 if ( defined $transport_cost_matrix ) {
804 my $allocations = _allocateWithTransportCostMatrix(
805 $hold_requests, $available_items, $branches_to_use, $libraries,
806 $transport_cost_matrix, \%allocated_items, \%items_by_itemnumber
808 for my $allocation (@$allocations) {
809 $item_map{ $allocation->[0] } = $allocation->[1];
810 $num_items_remaining--;
815 # group available items by branch
816 my %items_by_branch = ();
817 foreach my $item (@$available_items) {
818 next unless $item->{holdallowed} ne 'not_allowed';
820 push @{ $items_by_branch{ $item->{holdingbranch} } }, $item
821 unless exists $allocated_items{ $item->{itemnumber} };
823 return \%item_map unless keys %items_by_branch;
825 # now handle the title-level requests
826 $num_items_remaining = scalar(@$available_items) - scalar(keys %allocated_items);
828 foreach my $request (@$hold_requests) {
829 last if $num_items_remaining == 0;
830 next if $request->{allocated};
831 next if defined($request->{itemnumber}); # already handled these
833 # HoldsQueuePrioritizeBranch check
834 # ********************************
835 my $pickup_branch = $request->{branchcode} || $request->{borrowerbranch};
836 my ( $itemnumber, $holdingbranch ); # These variables are used for tracking the filling of the hold
837 # $itemnumber, when set, is the item that has been chosen for the hold
838 # $holdingbranch gets set to the pickup branch of the request if there are items held at that branch
839 # otherwise it gets set to the least cost branch of the transport cost matrix
840 # otherwise it gets sets to the first branch from the list of branches to pull from
842 my $holding_branch_items = $items_by_branch{$pickup_branch};
843 if ($holding_branch_items) {
844 $holdingbranch = $pickup_branch;
847 my $priority_branch = C4::Context->preference('HoldsQueuePrioritizeBranch') // 'homebranch';
848 foreach my $item (@$holding_branch_items) {
849 if ( _can_item_fill_request( $item, $request, $libraries )
850 && $request->{borrowerbranch} eq $item->{$priority_branch} )
852 $itemnumber = $item->{itemnumber};
856 # End HoldsQueuePrioritizeBranch check
857 # ********************************
860 # Not found yet, fall back to basics
861 unless ($itemnumber) {
862 if ($branches_to_use) {
863 $pull_branches = $branches_to_use;
865 $pull_branches = [keys %items_by_branch];
867 $holdingbranch ||= $pull_branches->[0]; # We set this as the first from the list of pull branches
868 # unless we set it above to the pickupbranch or the least cost branch
869 # FIXME: The intention is to follow StaticHoldsQueueWeight, but we don't check that pref
871 # Try picking items where the home and pickup branch match first
872 foreach my $branch (@$pull_branches) {
873 my $holding_branch_items = $items_by_branch{$branch}
876 foreach my $item (@$holding_branch_items) {
877 if ( $pickup_branch eq $item->{homebranch}
878 && _can_item_fill_request( $item, $request, $libraries ) )
880 $itemnumber = $item->{itemnumber};
881 $holdingbranch = $branch;
888 # Now try items from the least cost branch based on the transport cost matrix or StaticHoldsQueueWeight
889 unless ( $itemnumber || !$holdingbranch) {
890 foreach my $current_item ( @{ $items_by_branch{$holdingbranch} } ) {
891 next unless _can_item_fill_request( $current_item, $request, $libraries );
893 $itemnumber = $current_item->{itemnumber};
894 last; # quit this loop as soon as we have a suitable item
898 # Now try for items for any item that can fill this hold
899 unless ( $itemnumber ) {
900 foreach my $branch (@$pull_branches) {
901 my $holding_branch_items = $items_by_branch{$branch}
904 foreach my $item (@$holding_branch_items) {
905 if( _can_item_fill_request( $item, $request, $libraries ) ){
906 $itemnumber = $item->{itemnumber};
907 $holdingbranch = $branch;
917 my $holding_branch_items = $items_by_branch{$holdingbranch}
918 or die "Have $itemnumber, $holdingbranch, but no items!";
919 @$holding_branch_items = grep { $_->{itemnumber} != $itemnumber } @$holding_branch_items;
920 delete $items_by_branch{$holdingbranch} unless @$holding_branch_items;
922 $item_map{$itemnumber} = {
923 borrowernumber => $request->{borrowernumber},
924 biblionumber => $request->{biblionumber},
925 holdingbranch => $holdingbranch,
926 pickup_branch => $pickup_branch,
927 reserve_id => $request->{reserve_id},
928 item_level => $request->{item_level_hold},
929 reservedate => $request->{reservedate},
930 reservenotes => $request->{reservenotes},
932 $num_items_remaining--;
939 =head2 _can_item_fill_request
941 my $bool = _can_item_fill_request( $item, $request, $libraries );
943 This is an internal function of MapItemsToHoldRequests for checking an item against a hold. It uses the custom hashes for item and hold information
948 sub _can_item_fill_request {
949 my ( $item, $request, $libraries ) = @_;
951 # Don't fill item level holds that contravene the hold pickup policy at this time
952 return unless _checkHoldPolicy( $item, $request );
954 # If hold itemtype is set, item's itemtype must match
955 return unless ( !$request->{itemtype}
956 || $item->{itype} eq $request->{itemtype} );
958 # If hold item_group is set, item's item_group must match
961 !$request->{item_group_id}
962 || ( $item->{_object}->item_group
963 && $item->{_object}->item_group->id eq $request->{item_group_id} )
967 unless $item->{_object}->can_be_transferred( { to => $libraries->{ $request->{branchcode} } } );
974 =head2 CreatePickListFromItemMap
978 sub CreatePicklistFromItemMap {
979 my $item_map = shift;
981 my $dbh = C4::Context->dbh;
983 my $sth_load=$dbh->prepare("
984 INSERT INTO tmp_holdsqueue (biblionumber,itemnumber,barcode,surname,firstname,phone,borrowernumber,
985 cardnumber,reservedate,title, itemcallnumber,
986 holdingbranch,pickbranch,notes, item_level_request)
987 VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
990 foreach my $itemnumber (sort keys %$item_map) {
991 my $mapped_item = $item_map->{$itemnumber};
992 my $biblionumber = $mapped_item->{biblionumber};
993 my $borrowernumber = $mapped_item->{borrowernumber};
994 my $pickbranch = $mapped_item->{pickup_branch};
995 my $holdingbranch = $mapped_item->{holdingbranch};
996 my $reservedate = $mapped_item->{reservedate};
997 my $reservenotes = $mapped_item->{reservenotes};
998 my $item_level = $mapped_item->{item_level};
1000 my $item = Koha::Items->find($itemnumber);
1001 my $barcode = $item->barcode;
1002 my $itemcallnumber = $item->itemcallnumber;
1004 my $patron = Koha::Patrons->find( $borrowernumber );
1005 my $cardnumber = $patron->cardnumber;
1006 my $surname = $patron->surname;
1007 my $firstname = $patron->firstname;
1008 my $phone = $patron->phone;
1010 my $biblio = Koha::Biblios->find( $biblionumber );
1011 my $title = $biblio->title;
1013 $sth_load->execute($biblionumber, $itemnumber, $barcode, $surname, $firstname, $phone, $borrowernumber,
1014 $cardnumber, $reservedate, $title, $itemcallnumber,
1015 $holdingbranch, $pickbranch, $reservenotes, $item_level);
1019 =head2 AddToHoldTargetMap
1023 sub AddToHoldTargetMap {
1024 my $item_map = shift;
1026 my $dbh = C4::Context->dbh;
1027 my $schema = Koha::Database->new->schema;
1030 INSERT INTO hold_fill_targets (borrowernumber, biblionumber, itemnumber, source_branchcode, item_level_request, reserve_id) VALUES (?, ?, ?, ?, ?, ?)
1032 my $sth_insert = $dbh->prepare($insert_sql);
1034 foreach my $itemnumber ( keys %$item_map ) {
1035 my $mapped_item = $item_map->{$itemnumber};
1038 $dbh->do( 'DELETE FROM hold_fill_targets WHERE itemnumber = ?', {}, $itemnumber );
1039 $sth_insert->execute(
1040 $mapped_item->{borrowernumber}, $mapped_item->{biblionumber}, $itemnumber,
1041 $mapped_item->{holdingbranch}, $mapped_item->{item_level}, $mapped_item->{reserve_id}
1048 # Helper functions, not part of any interface
1051 return $_[0] unless $_[0];
1057 sub load_branches_to_pull_from {
1058 my $use_transport_cost_matrix = shift;
1060 my @branches_to_use;
1062 unless ( $use_transport_cost_matrix ) {
1063 my $static_branch_list = C4::Context->preference("StaticHoldsQueueWeight");
1064 @branches_to_use = map { _trim($_) } split( /,/, $static_branch_list )
1065 if $static_branch_list;
1069 Koha::Database->new()->schema()->resultset('Branch')
1070 ->get_column('branchcode')->all()
1071 unless (@branches_to_use);
1073 @branches_to_use = shuffle(@branches_to_use)
1074 if C4::Context->preference("RandomizeHoldsQueueWeight");
1076 my $today = dt_from_string();
1077 if ( C4::Context->preference('HoldsQueueSkipClosed') ) {
1078 @branches_to_use = grep {
1079 !Koha::Calendar->new( branchcode => $_ )
1080 ->is_holiday( $today )
1084 return \@branches_to_use;
1087 sub least_cost_branch {
1090 my ($to, $from, $transport_cost_matrix) = @_;
1092 # Nothing really spectacular: supply to branch, a list of potential from branches
1093 # and find the minimum from - to value from the transport_cost_matrix
1094 return $from->[0] if ( @$from == 1 && $transport_cost_matrix->{$to}{$from->[0]}->{disable_transfer} != 1 );
1096 # If the pickup library is in the list of libraries to pull from,
1097 # return that library right away, it is obviously the least costly
1098 return ($to) if any { $_ eq $to } @$from;
1100 my ($least_cost, @branch);
1102 my $cell = $transport_cost_matrix->{$to}{$_};
1103 next if $cell->{disable_transfer};
1105 my $cost = $cell->{cost};
1106 next unless defined $cost; # XXX should this be reported?
1108 unless (defined $least_cost) {
1109 $least_cost = $cost;
1114 next if $cost > $least_cost;
1116 if ($cost == $least_cost) {
1122 $least_cost = $cost;
1127 # XXX return a random @branch with minimum cost instead of the first one;
1128 # return $branch[0] if @branch == 1;
1131 =head3 update_queue_for_biblio
1133 my $result = update_queue_for_biblio(
1135 biblio_id => $biblio_id,
1136 [ branches_to_use => $branches_to_use,
1137 transport_cost_matrix => $transport_cost_matrix,
1139 unallocated => $unallocated, ]
1143 Given a I<biblio_id>, this method calculates and sets the holds queue entries
1144 for the biblio's holds, and the hold fill targets (items).
1148 It return a hashref containing:
1152 =item I<requests>: the pending holds count for the biblio.
1154 =item I<available_items> the count of items that are available to fill holds for the biblio.
1156 =item I<mapped_items> the total items that got mapped.
1160 =head4 Optional parameters
1164 =item I<branches_to_use> a list of branchcodes to be used to restrict which items can be used.
1166 =item I<transport_cost_matrix> is the output of C<TransportCostMatrix>.
1168 =item I<delete> tells the method to delete prior entries on the related tables for the biblio_id.
1170 =item I<unallocated> tells the method to limit the holds to those not in the holds queue, should not
1171 be passed at the same time as delete.
1175 Note: All the optional parameters will be calculated in the method if omitted. They
1176 are allowed to be passed to avoid calculating them many times inside loops.
1180 sub update_queue_for_biblio {
1182 my $biblio_id = $args->{biblio_id};
1185 # We need to empty the queue for this biblio unless CreateQueue has emptied the entire queue for rebuilding
1186 if ( $args->{delete} ) {
1187 my $dbh = C4::Context->dbh;
1189 $dbh->do("DELETE FROM tmp_holdsqueue WHERE biblionumber=$biblio_id");
1190 $dbh->do("DELETE FROM hold_fill_targets WHERE biblionumber=$biblio_id");
1193 my $hold_requests = GetPendingHoldRequestsForBib({ biblionumber => $biblio_id, unallocated => $args->{unallocated} });
1194 $result->{requests} = scalar( @{$hold_requests} );
1195 # No need to check anything else if there are no holds to fill
1196 return $result unless $result->{requests};
1198 my $branches_to_use = $args->{branches_to_use} // load_branches_to_pull_from( C4::Context->preference('UseTransportCostMatrix') );
1199 my $transport_cost_matrix;
1201 if ( !exists $args->{transport_cost_matrix}
1202 && C4::Context->preference('UseTransportCostMatrix') ) {
1203 $transport_cost_matrix = TransportCostMatrix();
1205 $transport_cost_matrix = $args->{transport_cost_matrix};
1208 my $available_items = GetItemsAvailableToFillHoldRequestsForBib( $biblio_id, $branches_to_use );
1210 $result->{available_items} = scalar( @{$available_items} );
1212 my $item_map = MapItemsToHoldRequests( $hold_requests, $available_items, $branches_to_use, $transport_cost_matrix );
1213 $result->{mapped_items} = scalar( keys %{$item_map} );
1216 CreatePicklistFromItemMap($item_map);
1217 AddToHoldTargetMap($item_map);