Bug 14153: Noisy warns in admin/transport-cost-matrix.pl
[koha.git] / C4 / HoldsQueue.pm
blobf5a9be733c1f2f4e36fe9c9306a256c10ad7c5da
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
22 use strict;
23 use warnings;
25 use C4::Context;
26 use C4::Search;
27 use C4::Items;
28 use C4::Branch;
29 use C4::Circulation;
30 use C4::Members;
31 use C4::Biblio;
33 use List::Util qw(shuffle);
34 use List::MoreUtils qw(any);
35 use Data::Dumper;
37 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
38 BEGIN {
39 $VERSION = 3.03;
40 require Exporter;
41 @ISA = qw(Exporter);
42 @EXPORT_OK = qw(
43 &CreateQueue
44 &GetHoldsQueueItems
46 &TransportCostMatrix
47 &UpdateTransportCostMatrix
52 =head1 FUNCTIONS
54 =head2 TransportCostMatrix
56 TransportCostMatrix();
58 Returns Transport Cost Matrix as a hashref <to branch code> => <from branch code> => cost
60 =cut
62 sub TransportCostMatrix {
63 my $dbh = C4::Context->dbh;
64 my $transport_costs = $dbh->selectall_arrayref("SELECT * FROM transport_cost",{ Slice => {} });
66 my %transport_cost_matrix;
67 foreach (@$transport_costs) {
68 my $from = $_->{frombranch};
69 my $to = $_->{tobranch};
70 my $cost = $_->{cost};
71 my $disabled = $_->{disable_transfer};
72 $transport_cost_matrix{$to}{$from} = { cost => $cost, disable_transfer => $disabled };
74 return \%transport_cost_matrix;
77 =head2 UpdateTransportCostMatrix
79 UpdateTransportCostMatrix($records);
81 Updates full Transport Cost Matrix table. $records is an arrayref of records.
82 Records: { frombranch => <code>, tobranch => <code>, cost => <figure>, disable_transfer => <0,1> }
84 =cut
86 sub UpdateTransportCostMatrix {
87 my ($records) = @_;
88 my $dbh = C4::Context->dbh;
90 my $sth = $dbh->prepare("INSERT INTO transport_cost (frombranch, tobranch, cost, disable_transfer) VALUES (?, ?, ?, ?)");
92 $dbh->do("TRUNCATE TABLE transport_cost");
93 foreach (@$records) {
94 my $cost = $_->{cost};
95 my $from = $_->{frombranch};
96 my $to = $_->{tobranch};
97 if ($_->{disable_transfer}) {
98 $cost ||= 0;
100 elsif ( !defined ($cost) || ($cost !~ m/(0|[1-9][0-9]*)(\.[0-9]*)?/o) ) {
101 warn "Invalid $from -> $to cost $cost - must be a number >= 0, disablig";
102 $cost = 0;
103 $_->{disable_transfer} = 1;
105 $sth->execute( $from, $to, $cost, $_->{disable_transfer} ? 1 : 0 );
109 =head2 GetHoldsQueueItems
111 GetHoldsQueueItems($branch);
113 Returns hold queue for a holding branch. If branch is omitted, then whole queue is returned
115 =cut
117 sub GetHoldsQueueItems {
118 my ($branchlimit) = @_;
119 my $dbh = C4::Context->dbh;
121 my @bind_params = ();
122 my $query = q/SELECT tmp_holdsqueue.*, biblio.author, items.ccode, items.itype, biblioitems.itemtype, items.location, items.enumchron, items.cn_sort, biblioitems.publishercode,biblio.copyrightdate,biblioitems.publicationyear,biblioitems.pages,biblioitems.size,biblioitems.publicationyear,biblioitems.isbn,items.copynumber
123 FROM tmp_holdsqueue
124 JOIN biblio USING (biblionumber)
125 LEFT JOIN biblioitems USING (biblionumber)
126 LEFT JOIN items USING ( itemnumber)
128 if ($branchlimit) {
129 $query .=" WHERE tmp_holdsqueue.holdingbranch = ?";
130 push @bind_params, $branchlimit;
132 $query .= " ORDER BY ccode, location, cn_sort, author, title, pickbranch, reservedate";
133 my $sth = $dbh->prepare($query);
134 $sth->execute(@bind_params);
135 my $items = [];
136 while ( my $row = $sth->fetchrow_hashref ){
137 my $record = GetMarcBiblio($row->{biblionumber});
138 if ($record){
139 $row->{subtitle} = [ map { $_->{subfield} } @{ GetRecordValue( 'subtitle', $record, '' ) } ];
140 $row->{parts} = GetRecordValue('parts',$record,'')->[0]->{subfield};
141 $row->{numbers} = GetRecordValue('numbers',$record,'')->[0]->{subfield};
144 # return the bib-level or item-level itype per syspref
145 if (!C4::Context->preference('item-level_itypes')) {
146 $row->{itype} = $row->{itemtype};
148 delete $row->{itemtype};
150 push @$items, $row;
152 return $items;
155 =head2 CreateQueue
157 CreateQueue();
159 Top level function that turns reserves into tmp_holdsqueue and hold_fill_targets.
161 =cut
163 sub CreateQueue {
164 my $dbh = C4::Context->dbh;
166 $dbh->do("DELETE FROM tmp_holdsqueue"); # clear the old table for new info
167 $dbh->do("DELETE FROM hold_fill_targets");
169 my $total_bibs = 0;
170 my $total_requests = 0;
171 my $total_available_items = 0;
172 my $num_items_mapped = 0;
174 my $branches_to_use;
175 my $transport_cost_matrix;
176 my $use_transport_cost_matrix = C4::Context->preference("UseTransportCostMatrix");
177 if ($use_transport_cost_matrix) {
178 $transport_cost_matrix = TransportCostMatrix();
179 unless (keys %$transport_cost_matrix) {
180 warn "UseTransportCostMatrix set to yes, but matrix not populated";
181 undef $transport_cost_matrix;
184 unless ($transport_cost_matrix) {
185 $branches_to_use = load_branches_to_pull_from();
188 my $bibs_with_pending_requests = GetBibsWithPendingHoldRequests();
190 foreach my $biblionumber (@$bibs_with_pending_requests) {
191 $total_bibs++;
192 my $hold_requests = GetPendingHoldRequestsForBib($biblionumber);
193 my $available_items = GetItemsAvailableToFillHoldRequestsForBib($biblionumber, $branches_to_use);
194 $total_requests += scalar(@$hold_requests);
195 $total_available_items += scalar(@$available_items);
197 my $item_map = MapItemsToHoldRequests($hold_requests, $available_items, $branches_to_use, $transport_cost_matrix);
198 $item_map or next;
199 my $item_map_size = scalar(keys %$item_map)
200 or next;
202 $num_items_mapped += $item_map_size;
203 CreatePicklistFromItemMap($item_map);
204 AddToHoldTargetMap($item_map);
205 if (($item_map_size < scalar(@$hold_requests )) and
206 ($item_map_size < scalar(@$available_items))) {
207 # DOUBLE CHECK, but this is probably OK - unfilled item-level requests
208 # FIXME
209 #warn "unfilled requests for $biblionumber";
210 #warn Dumper($hold_requests), Dumper($available_items), Dumper($item_map);
215 =head2 GetBibsWithPendingHoldRequests
217 my $biblionumber_aref = GetBibsWithPendingHoldRequests();
219 Return an arrayref of the biblionumbers of all bibs
220 that have one or more unfilled hold requests.
222 =cut
224 sub GetBibsWithPendingHoldRequests {
225 my $dbh = C4::Context->dbh;
227 my $bib_query = "SELECT DISTINCT biblionumber
228 FROM reserves
229 WHERE found IS NULL
230 AND priority > 0
231 AND reservedate <= CURRENT_DATE()
232 AND suspend = 0
234 my $sth = $dbh->prepare($bib_query);
236 $sth->execute();
237 my $biblionumbers = $sth->fetchall_arrayref();
239 return [ map { $_->[0] } @$biblionumbers ];
242 =head2 GetPendingHoldRequestsForBib
244 my $requests = GetPendingHoldRequestsForBib($biblionumber);
246 Returns an arrayref of hashrefs to pending, unfilled hold requests
247 on the bib identified by $biblionumber. The following keys
248 are present in each hashref:
250 biblionumber
251 borrowernumber
252 itemnumber
253 priority
254 branchcode
255 reservedate
256 reservenotes
257 borrowerbranch
259 The arrayref is sorted in order of increasing priority.
261 =cut
263 sub GetPendingHoldRequestsForBib {
264 my $biblionumber = shift;
266 my $dbh = C4::Context->dbh;
268 my $request_query = "SELECT biblionumber, borrowernumber, itemnumber, priority, reserves.branchcode,
269 reservedate, reservenotes, borrowers.branchcode AS borrowerbranch
270 FROM reserves
271 JOIN borrowers USING (borrowernumber)
272 WHERE biblionumber = ?
273 AND found IS NULL
274 AND priority > 0
275 AND reservedate <= CURRENT_DATE()
276 AND suspend = 0
277 ORDER BY priority";
278 my $sth = $dbh->prepare($request_query);
279 $sth->execute($biblionumber);
281 my $requests = $sth->fetchall_arrayref({});
282 return $requests;
286 =head2 GetItemsAvailableToFillHoldRequestsForBib
288 my $available_items = GetItemsAvailableToFillHoldRequestsForBib($biblionumber, $branches_ar);
290 Returns an arrayref of items available to fill hold requests
291 for the bib identified by C<$biblionumber>. An item is available
292 to fill a hold request if and only if:
294 * it is not on loan
295 * it is not withdrawn
296 * it is not marked notforloan
297 * it is not currently in transit
298 * it is not lost
299 * it is not sitting on the hold shelf
300 * it is not damaged (unless AllowHoldsOnDamagedItems is on)
302 =cut
304 sub GetItemsAvailableToFillHoldRequestsForBib {
305 my ($biblionumber, $branches_to_use) = @_;
307 my $dbh = C4::Context->dbh;
308 my $items_query = "SELECT itemnumber, homebranch, holdingbranch, itemtypes.itemtype AS itype
309 FROM items ";
311 if (C4::Context->preference('item-level_itypes')) {
312 $items_query .= "LEFT JOIN itemtypes ON (itemtypes.itemtype = items.itype) ";
313 } else {
314 $items_query .= "JOIN biblioitems USING (biblioitemnumber)
315 LEFT JOIN itemtypes USING (itemtype) ";
317 $items_query .= "WHERE items.notforloan = 0
318 AND holdingbranch IS NOT NULL
319 AND itemlost = 0
320 AND withdrawn = 0";
321 $items_query .= " AND damaged = 0" unless C4::Context->preference('AllowHoldsOnDamagedItems');
322 $items_query .= " AND items.onloan IS NULL
323 AND (itemtypes.notforloan IS NULL OR itemtypes.notforloan = 0)
324 AND itemnumber NOT IN (
325 SELECT itemnumber
326 FROM reserves
327 WHERE biblionumber = ?
328 AND itemnumber IS NOT NULL
329 AND (found IS NOT NULL OR priority = 0)
331 AND items.biblionumber = ?";
333 my @params = ($biblionumber, $biblionumber);
334 if ($branches_to_use && @$branches_to_use) {
335 $items_query .= " AND holdingbranch IN (" . join (",", map { "?" } @$branches_to_use) . ")";
336 push @params, @$branches_to_use;
338 my $sth = $dbh->prepare($items_query);
339 $sth->execute(@params);
341 my $itm = $sth->fetchall_arrayref({});
342 my @items = grep { ! scalar GetTransfers($_->{itemnumber}) } @$itm;
343 return [ grep {
344 my $rule = GetBranchItemRule($_->{homebranch}, $_->{itype});
345 $_->{holdallowed} = $rule->{holdallowed};
346 } @items ];
349 =head2 MapItemsToHoldRequests
351 MapItemsToHoldRequests($hold_requests, $available_items, $branches, $transport_cost_matrix)
353 =cut
355 sub MapItemsToHoldRequests {
356 my ($hold_requests, $available_items, $branches_to_use, $transport_cost_matrix) = @_;
358 # handle trival cases
359 return unless scalar(@$hold_requests) > 0;
360 return unless scalar(@$available_items) > 0;
362 # identify item-level requests
363 my %specific_items_requested = map { $_->{itemnumber} => 1 }
364 grep { defined($_->{itemnumber}) }
365 @$hold_requests;
367 # group available items by itemnumber
368 my %items_by_itemnumber = map { $_->{itemnumber} => $_ } @$available_items;
370 # items already allocated
371 my %allocated_items = ();
373 # map of items to hold requests
374 my %item_map = ();
376 # figure out which item-level requests can be filled
377 my $num_items_remaining = scalar(@$available_items);
378 foreach my $request (@$hold_requests) {
379 last if $num_items_remaining == 0;
381 # is this an item-level request?
382 if (defined($request->{itemnumber})) {
383 # fill it if possible; if not skip it
384 if (exists $items_by_itemnumber{$request->{itemnumber}} and
385 not exists $allocated_items{$request->{itemnumber}}) {
386 $item_map{$request->{itemnumber}} = {
387 borrowernumber => $request->{borrowernumber},
388 biblionumber => $request->{biblionumber},
389 holdingbranch => $items_by_itemnumber{$request->{itemnumber}}->{holdingbranch},
390 pickup_branch => $request->{branchcode} || $request->{borrowerbranch},
391 item_level => 1,
392 reservedate => $request->{reservedate},
393 reservenotes => $request->{reservenotes},
395 $allocated_items{$request->{itemnumber}}++;
396 $num_items_remaining--;
398 } else {
399 # it's title-level request that will take up one item
400 $num_items_remaining--;
404 # group available items by branch
405 my %items_by_branch = ();
406 foreach my $item (@$available_items) {
407 next unless $item->{holdallowed};
409 push @{ $items_by_branch{ $item->{holdingbranch} } }, $item
410 unless exists $allocated_items{ $item->{itemnumber} };
412 return \%item_map unless keys %items_by_branch;
414 # now handle the title-level requests
415 $num_items_remaining = scalar(@$available_items) - scalar(keys %allocated_items);
416 my $pull_branches;
417 foreach my $request (@$hold_requests) {
418 last if $num_items_remaining == 0;
419 next if defined($request->{itemnumber}); # already handled these
421 # look for local match first
422 my $pickup_branch = $request->{branchcode} || $request->{borrowerbranch};
423 my ($itemnumber, $holdingbranch);
425 my $holding_branch_items = $items_by_branch{$pickup_branch};
426 if ( $holding_branch_items ) {
427 foreach my $item (@$holding_branch_items) {
428 if ( $request->{borrowerbranch} eq $item->{homebranch} ) {
429 $itemnumber = $item->{itemnumber};
430 last;
433 $holdingbranch = $pickup_branch;
435 elsif ($transport_cost_matrix) {
436 $pull_branches = [keys %items_by_branch];
437 $holdingbranch = least_cost_branch( $pickup_branch, $pull_branches, $transport_cost_matrix );
438 if ( $holdingbranch ) {
440 my $holding_branch_items = $items_by_branch{$holdingbranch};
441 foreach my $item (@$holding_branch_items) {
442 next if $request->{borrowerbranch} ne $item->{homebranch};
444 $itemnumber = $item->{itemnumber};
445 last;
448 else {
449 next;
453 unless ($itemnumber) {
454 # not found yet, fall back to basics
455 if ($branches_to_use) {
456 $pull_branches = $branches_to_use;
457 } else {
458 $pull_branches = [keys %items_by_branch];
461 # Try picking items where the home and pickup branch match first
462 PULL_BRANCHES:
463 foreach my $branch (@$pull_branches) {
464 my $holding_branch_items = $items_by_branch{$branch}
465 or next;
467 $holdingbranch ||= $branch;
468 foreach my $item (@$holding_branch_items) {
469 next if $pickup_branch ne $item->{homebranch};
470 next if ( $item->{holdallowed} == 1 && $item->{homebranch} ne $request->{borrowerbranch} );
472 $itemnumber = $item->{itemnumber};
473 $holdingbranch = $branch;
474 last PULL_BRANCHES;
478 # Now try items from the least cost branch based on the transport cost matrix or StaticHoldsQueueWeight
479 unless ( $itemnumber ) {
480 foreach my $current_item ( @{ $items_by_branch{$holdingbranch} } ) {
481 if ( $holdingbranch && ( $current_item->{holdallowed} == 2 || $request->{borrowerbranch} eq $current_item->{homebranch} ) ) {
482 $itemnumber = $current_item->{itemnumber};
483 last; # quit this loop as soon as we have a suitable item
488 # Now try for items for any item that can fill this hold
489 unless ( $itemnumber ) {
490 PULL_BRANCHES2:
491 foreach my $branch (@$pull_branches) {
492 my $holding_branch_items = $items_by_branch{$branch}
493 or next;
495 foreach my $item (@$holding_branch_items) {
496 next if ( $item->{holdallowed} == 1 && $item->{homebranch} ne $request->{borrowerbranch} );
498 $itemnumber = $item->{itemnumber};
499 $holdingbranch = $branch;
500 last PULL_BRANCHES2;
506 if ($itemnumber) {
507 my $holding_branch_items = $items_by_branch{$holdingbranch}
508 or die "Have $itemnumber, $holdingbranch, but no items!";
509 @$holding_branch_items = grep { $_->{itemnumber} != $itemnumber } @$holding_branch_items;
510 delete $items_by_branch{$holdingbranch} unless @$holding_branch_items;
512 $item_map{$itemnumber} = {
513 borrowernumber => $request->{borrowernumber},
514 biblionumber => $request->{biblionumber},
515 holdingbranch => $holdingbranch,
516 pickup_branch => $pickup_branch,
517 item_level => 0,
518 reservedate => $request->{reservedate},
519 reservenotes => $request->{reservenotes},
521 $num_items_remaining--;
524 return \%item_map;
527 =head2 CreatePickListFromItemMap
529 =cut
531 sub CreatePicklistFromItemMap {
532 my $item_map = shift;
534 my $dbh = C4::Context->dbh;
536 my $sth_load=$dbh->prepare("
537 INSERT INTO tmp_holdsqueue (biblionumber,itemnumber,barcode,surname,firstname,phone,borrowernumber,
538 cardnumber,reservedate,title, itemcallnumber,
539 holdingbranch,pickbranch,notes, item_level_request)
540 VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
543 foreach my $itemnumber (sort keys %$item_map) {
544 my $mapped_item = $item_map->{$itemnumber};
545 my $biblionumber = $mapped_item->{biblionumber};
546 my $borrowernumber = $mapped_item->{borrowernumber};
547 my $pickbranch = $mapped_item->{pickup_branch};
548 my $holdingbranch = $mapped_item->{holdingbranch};
549 my $reservedate = $mapped_item->{reservedate};
550 my $reservenotes = $mapped_item->{reservenotes};
551 my $item_level = $mapped_item->{item_level};
553 my $item = GetItem($itemnumber);
554 my $barcode = $item->{barcode};
555 my $itemcallnumber = $item->{itemcallnumber};
557 my $borrower = GetMember('borrowernumber'=>$borrowernumber);
558 my $cardnumber = $borrower->{'cardnumber'};
559 my $surname = $borrower->{'surname'};
560 my $firstname = $borrower->{'firstname'};
561 my $phone = $borrower->{'phone'};
563 my $bib = GetBiblioData($biblionumber);
564 my $title = $bib->{title};
566 $sth_load->execute($biblionumber, $itemnumber, $barcode, $surname, $firstname, $phone, $borrowernumber,
567 $cardnumber, $reservedate, $title, $itemcallnumber,
568 $holdingbranch, $pickbranch, $reservenotes, $item_level);
572 =head2 AddToHoldTargetMap
574 =cut
576 sub AddToHoldTargetMap {
577 my $item_map = shift;
579 my $dbh = C4::Context->dbh;
581 my $insert_sql = q(
582 INSERT INTO hold_fill_targets (borrowernumber, biblionumber, itemnumber, source_branchcode, item_level_request)
583 VALUES (?, ?, ?, ?, ?)
585 my $sth_insert = $dbh->prepare($insert_sql);
587 foreach my $itemnumber (keys %$item_map) {
588 my $mapped_item = $item_map->{$itemnumber};
589 $sth_insert->execute($mapped_item->{borrowernumber}, $mapped_item->{biblionumber}, $itemnumber,
590 $mapped_item->{holdingbranch}, $mapped_item->{item_level});
594 # Helper functions, not part of any interface
596 sub _trim {
597 return $_[0] unless $_[0];
598 $_[0] =~ s/^\s+//;
599 $_[0] =~ s/\s+$//;
600 $_[0];
603 sub load_branches_to_pull_from {
604 my $static_branch_list = C4::Context->preference("StaticHoldsQueueWeight")
605 or return;
607 my @branches_to_use = map _trim($_), split /,/, $static_branch_list;
609 @branches_to_use = shuffle(@branches_to_use) if C4::Context->preference("RandomizeHoldsQueueWeight");
611 return \@branches_to_use;
614 sub least_cost_branch {
616 #$from - arrayref
617 my ($to, $from, $transport_cost_matrix) = @_;
619 # Nothing really spectacular: supply to branch, a list of potential from branches
620 # and find the minimum from - to value from the transport_cost_matrix
621 return $from->[0] if ( @$from == 1 && $transport_cost_matrix->{$to}{$from->[0]}->{disable_transfer} != 1 );
623 # If the pickup library is in the list of libraries to pull from,
624 # return that library right away, it is obviously the least costly
625 return ($to) if any { $_ eq $to } @$from;
627 my ($least_cost, @branch);
628 foreach (@$from) {
629 my $cell = $transport_cost_matrix->{$to}{$_};
630 next if $cell->{disable_transfer};
632 my $cost = $cell->{cost};
633 next unless defined $cost; # XXX should this be reported?
635 unless (defined $least_cost) {
636 $least_cost = $cost;
637 push @branch, $_;
638 next;
641 next if $cost > $least_cost;
643 if ($cost == $least_cost) {
644 push @branch, $_;
645 next;
648 @branch = ($_);
649 $least_cost = $cost;
652 return $branch[0];
654 # XXX return a random @branch with minimum cost instead of the first one;
655 # return $branch[0] if @branch == 1;