C4/Reserves.pm

   1 package C4::Reserves;
   2
   3 # Copyright 2000-2002 Katipo Communications
   4 #           2006 SAN Ouest Provence
   5 #           2007-2010 BibLibre Paul POULAIN
   6 #           2011 Catalyst IT
   7 #
   8 # This file is part of Koha.
   9 #
  10 # Koha is free software; you can redistribute it and/or modify it
  11 # under the terms of the GNU General Public License as published by
  12 # the Free Software Foundation; either version 3 of the License, or
  13 # (at your option) any later version.
  14 #
  15 # Koha is distributed in the hope that it will be useful, but
  16 # WITHOUT ANY WARRANTY; without even the implied warranty of
  17 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18 # GNU General Public License for more details.
  19 #
  20 # You should have received a copy of the GNU General Public License
  21 # along with Koha; if not, see <http://www.gnu.org/licenses>.
  22
  23
  24 use Modern::Perl;
  25
  26 use C4::Accounts;
  27 use C4::Biblio;
  28 use C4::Circulation;
  29 use C4::Context;
  30 use C4::Items;
  31 use C4::Letters;
  32 use C4::Log;
  33 use C4::Members::Messaging;
  34 use C4::Members;
  35 use Koha::Account::Lines;
  36 use Koha::Biblios;
  37 use Koha::Calendar;
  38 use Koha::CirculationRules;
  39 use Koha::Database;
  40 use Koha::DateUtils;
  41 use Koha::Hold;
  42 use Koha::Holds;
  43 use Koha::ItemTypes;
  44 use Koha::Items;
  45 use Koha::Libraries;
  46 use Koha::Old::Hold;
  47 use Koha::Patrons;
  48 use Koha::Plugins;
  49
  50 use Carp;
  51 use Data::Dumper;
  52 use List::MoreUtils qw( firstidx any );
  53
  54 use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
  55
  56 =head1 NAME
  57
  58 C4::Reserves - Koha functions for dealing with reservation.
  59
  60 =head1 SYNOPSIS
  61
  62   use C4::Reserves;
  63
  64 =head1 DESCRIPTION
  65
  66 This modules provides somes functions to deal with reservations.
  67
  68   Reserves are stored in reserves table.
  69   The following columns contains important values :
  70   - priority >0      : then the reserve is at 1st stage, and not yet affected to any item.
  71              =0      : then the reserve is being dealed
  72   - found : NULL         : means the patron requested the 1st available, and we haven't chosen the item
  73             T(ransit)    : the reserve is linked to an item but is in transit to the pickup branch
  74             W(aiting)    : the reserve is linked to an item, is at the pickup branch, and is waiting on the hold shelf
  75             F(inished)   : the reserve has been completed, and is done
  76             P(rocessing) : reserved item has been returned using self-check machine and reserve needs to be confirmed
  77                            by librarian before notice is send and status changed to waiting.
  78                            Applicable only if HoldsNeedProcessingSIP system preference is set.
  79   - itemnumber : empty : the reserve is still unaffected to an item
  80                  filled: the reserve is attached to an item
  81   The complete workflow is :
  82   ==== 1st use case ====
  83   patron request a document, 1st available :                      P >0, F=NULL, I=NULL
  84   a library having it run "transfertodo", and clic on the list
  85          if there is no transfer to do, the reserve waiting
  86          patron can pick it up                                    P =0, F=W,    I=filled
  87          if there is a transfer to do, write in branchtransfer    P =0, F=T,    I=filled
  88            The pickup library receive the book, it check in       P =0, F=W,    I=filled
  89   The patron borrow the book                                      P =0, F=F,    I=filled
  90
  91   ==== 2nd use case ====
  92   patron requests a document, a given item,
  93     If pickup is holding branch                                   P =0, F=W,   I=filled
  94     If transfer needed, write in branchtransfer                   P =0, F=T,    I=filled
  95         The pickup library receive the book, it checks it in      P =0, F=W,    I=filled
  96   The patron borrow the book                                      P =0, F=F,    I=filled
  97
  98 =head1 FUNCTIONS
  99
 100 =cut
 101
 102 BEGIN {
 103     require Exporter;
 104     @ISA = qw(Exporter);
 105     @EXPORT = qw(
 106         &AddReserve
 107
 108         &GetReserveStatus
 109
 110         &GetOtherReserves
 111
 112         &ModReserveFill
 113         &ModReserveAffect
 114         &ModReserve
 115         &ModReserveStatus
 116         &ModReserveCancelAll
 117         &ModReserveMinusPriority
 118         &MoveReserve
 119
 120         &CheckReserves
 121         &CanBookBeReserved
 122         &CanItemBeReserved
 123         &CanReserveBeCanceledFromOpac
 124         &CancelExpiredReserves
 125
 126         &AutoUnsuspendReserves
 127
 128         &IsAvailableForItemLevelRequest
 129         ItemsAnyAvailableAndNotRestricted
 130
 131         &AlterPriority
 132         &ToggleLowestPriority
 133
 134         &ReserveSlip
 135         &ToggleSuspend
 136         &SuspendAll
 137
 138         &GetReservesControlBranch
 139
 140         IsItemOnHoldAndFound
 141
 142         GetMaxPatronHoldsForRecord
 143     );
 144     @EXPORT_OK = qw( MergeHolds );
 145 }
 146
 147 =head2 AddReserve
 148
 149     AddReserve(
 150         {
 151             branchcode       => $branchcode,
 152             borrowernumber   => $borrowernumber,
 153             biblionumber     => $biblionumber,
 154             priority         => $priority,
 155             reservation_date => $reservation_date,
 156             expiration_date  => $expiration_date,
 157             notes            => $notes,
 158             title            => $title,
 159             itemnumber       => $itemnumber,
 160             found            => $found,
 161             itemtype         => $itemtype,
 162         }
 163     );
 164
 165 Adds reserve and generates HOLDPLACED message.
 166
 167 The following tables are available witin the HOLDPLACED message:
 168
 169     branches
 170     borrowers
 171     biblio
 172     biblioitems
 173     items
 174     reserves
 175
 176 =cut
 177
 178 sub AddReserve {
 179     my ($params)       = @_;
 180     my $branch         = $params->{branchcode};
 181     my $borrowernumber = $params->{borrowernumber};
 182     my $biblionumber   = $params->{biblionumber};
 183     my $priority       = $params->{priority};
 184     my $resdate        = $params->{reservation_date};
 185     my $expdate        = $params->{expiration_date};
 186     my $notes          = $params->{notes};
 187     my $title          = $params->{title};
 188     my $checkitem      = $params->{itemnumber};
 189     my $found          = $params->{found};
 190     my $itemtype       = $params->{itemtype};
 191     my $non_priority   = $params->{non_priority};
 192
 193     $resdate = output_pref( { str => dt_from_string( $resdate ), dateonly => 1, dateformat => 'iso' })
 194         or output_pref({ dt => dt_from_string, dateonly => 1, dateformat => 'iso' });
 195
 196     $expdate = output_pref({ str => $expdate, dateonly => 1, dateformat => 'iso' });
 197
 198     # if we have an item selectionned, and the pickup branch is the same as the holdingbranch
 199     # of the document, we force the value $priority and $found .
 200     if ( $checkitem and not C4::Context->preference('ReservesNeedReturns') ) {
 201         my $item = Koha::Items->find( $checkitem ); # FIXME Prevent bad calls
 202
 203         if (
 204             # If item is already checked out, it cannot be set waiting
 205             !$item->onloan
 206
 207             # The item can't be waiting if it needs a transfer
 208             && $item->holdingbranch eq $branch
 209
 210             # Similarly, if in transit it can't be waiting
 211             && !$item->get_transfer
 212
 213             # If we can't hold damaged items, and it is damaged, it can't be waiting
 214             && ( $item->damaged && C4::Context->preference('AllowHoldsOnDamagedItems') || !$item->damaged )
 215
 216             # Lastly, if this already has holds, we shouldn't make it waiting for the new hold
 217             && !$item->current_holds->count )
 218         {
 219             $priority = 0;
 220             $found = 'W';
 221         }
 222     }
 223
 224     if ( C4::Context->preference('AllowHoldDateInFuture') ) {
 225
 226         # Make room in reserves for this before those of a later reserve date
 227         $priority = _ShiftPriorityByDateAndPriority( $biblionumber, $resdate, $priority );
 228     }
 229
 230     my $waitingdate;
 231
 232     # If the reserv had the waiting status, we had the value of the resdate
 233     if ( $found && $found eq 'W' ) {
 234         $waitingdate = $resdate;
 235     }
 236
 237     # Don't add itemtype limit if specific item is selected
 238     $itemtype = undef if $checkitem;
 239
 240     # updates take place here
 241     my $hold = Koha::Hold->new(
 242         {
 243             borrowernumber => $borrowernumber,
 244             biblionumber   => $biblionumber,
 245             reservedate    => $resdate,
 246             branchcode     => $branch,
 247             priority       => $priority,
 248             reservenotes   => $notes,
 249             itemnumber     => $checkitem,
 250             found          => $found,
 251             waitingdate    => $waitingdate,
 252             expirationdate => $expdate,
 253             itemtype       => $itemtype,
 254             item_level_hold => $checkitem ? 1 : 0,
 255             non_priority   => $non_priority ? 1 : 0,
 256         }
 257     )->store();
 258     $hold->set_waiting() if $found && $found eq 'W';
 259
 260     logaction( 'HOLDS', 'CREATE', $hold->id, Dumper($hold->unblessed) )
 261         if C4::Context->preference('HoldsLog');
 262
 263     my $reserve_id = $hold->id();
 264
 265     # add a reserve fee if needed
 266     if ( C4::Context->preference('HoldFeeMode') ne 'any_time_is_collected' ) {
 267         my $reserve_fee = GetReserveFee( $borrowernumber, $biblionumber );
 268         ChargeReserveFee( $borrowernumber, $reserve_fee, $title );
 269     }
 270
 271     _FixPriority({ biblionumber => $biblionumber});
 272
 273     # Send e-mail to librarian if syspref is active
 274     if(C4::Context->preference("emailLibrarianWhenHoldIsPlaced")){
 275         my $patron = Koha::Patrons->find( $borrowernumber );
 276         my $library = $patron->library;
 277         if ( my $letter =  C4::Letters::GetPreparedLetter (
 278             module => 'reserves',
 279             letter_code => 'HOLDPLACED',
 280             branchcode => $branch,
 281             lang => $patron->lang,
 282             tables => {
 283                 'branches'    => $library->unblessed,
 284                 'borrowers'   => $patron->unblessed,
 285                 'biblio'      => $biblionumber,
 286                 'biblioitems' => $biblionumber,
 287                 'items'       => $checkitem,
 288                 'reserves'    => $hold->unblessed,
 289             },
 290         ) ) {
 291
 292             my $branch_email_address = $library->inbound_email_address;
 293
 294             C4::Letters::EnqueueLetter(
 295                 {
 296                     letter                 => $letter,
 297                     borrowernumber         => $borrowernumber,
 298                     message_transport_type => 'email',
 299                     to_address             => $branch_email_address,
 300                 }
 301             );
 302         }
 303     }
 304
 305     Koha::Plugins->call('after_hold_create', $hold);
 306
 307     return $reserve_id;
 308 }
 309
 310 =head2 CanBookBeReserved
 311
 312   $canReserve = &CanBookBeReserved($borrowernumber, $biblionumber, $branchcode, $params)
 313   if ($canReserve eq 'OK') { #We can reserve this Item! }
 314
 315   $params are passed directly through to CanItemBeReserved
 316
 317 See CanItemBeReserved() for possible return values.
 318
 319 =cut
 320
 321 sub CanBookBeReserved{
 322     my ($borrowernumber, $biblionumber, $pickup_branchcode, $params) = @_;
 323
 324     # Check that patron have not checked out this biblio (if AllowHoldsOnPatronsPossessions set)
 325     if ( !C4::Context->preference('AllowHoldsOnPatronsPossessions')
 326         && C4::Circulation::CheckIfIssuedToPatron( $borrowernumber, $biblionumber ) ) {
 327         return { status =>'alreadypossession' };
 328     }
 329
 330     my @itemnumbers = Koha::Items->search({ biblionumber => $biblionumber})->get_column("itemnumber");
 331     #get items linked via host records
 332     my @hostitems = get_hostitemnumbers_of($biblionumber);
 333     if (@hostitems){
 334         push (@itemnumbers, @hostitems);
 335     }
 336
 337     my $canReserve = { status => '' };
 338     foreach my $itemnumber (@itemnumbers) {
 339         $canReserve = CanItemBeReserved( $borrowernumber, $itemnumber, $pickup_branchcode, $params );
 340         return { status => 'OK' } if $canReserve->{status} eq 'OK';
 341     }
 342     return $canReserve;
 343 }
 344
 345 =head2 CanItemBeReserved
 346
 347   $canReserve = &CanItemBeReserved($borrowernumber, $itemnumber, $branchcode, $params)
 348   if ($canReserve->{status} eq 'OK') { #We can reserve this Item! }
 349
 350   current params are:
 351   'ignore_found_holds' - if true holds that have been trapped are not counted
 352   toward the patron limit, used by checkHighHolds to avoid counting the hold we will fill with the
 353   current checkout against the high holds threshold
 354   'ignore_hold_counts' - we use this routine to check if an item can fill a hold - on this case we
 355   should not check if there are too many holds as we only csre about reservability
 356
 357 @RETURNS { status => OK },              if the Item can be reserved.
 358          { status => ageRestricted },   if the Item is age restricted for this borrower.
 359          { status => damaged },         if the Item is damaged.
 360          { status => cannotReserveFromOtherBranches }, if syspref 'canreservefromotherbranches' is OK.
 361          { status => branchNotInHoldGroup }, if borrower home library is not in hold group, and holds are only allowed from hold groups.
 362          { status => tooManyReserves, limit => $limit }, if the borrower has exceeded their maximum reserve amount.
 363          { status => notReservable },   if holds on this item are not allowed
 364          { status => libraryNotFound },   if given branchcode is not an existing library
 365          { status => libraryNotPickupLocation },   if given branchcode is not configured to be a pickup location
 366          { status => cannotBeTransferred }, if branch transfer limit applies on given item and branchcode
 367          { status => pickupNotInHoldGroup }, pickup location is not in hold group, and pickup locations are only allowed from hold groups.
 368
 369 =cut
 370
 371 sub CanItemBeReserved {
 372     my ( $borrowernumber, $itemnumber, $pickup_branchcode, $params ) = @_;
 373
 374     my $dbh = C4::Context->dbh;
 375     my $ruleitemtype;    # itemtype of the matching issuing rule
 376     my $allowedreserves  = 0; # Total number of holds allowed across all records, default to none
 377
 378     # we retrieve borrowers and items informations #
 379     # item->{itype} will come for biblioitems if necessery
 380     my $item       = Koha::Items->find($itemnumber);
 381     my $biblio     = $item->biblio;
 382     my $patron = Koha::Patrons->find( $borrowernumber );
 383     my $borrower = $patron->unblessed;
 384
 385     # If an item is damaged and we don't allow holds on damaged items, we can stop right here
 386     return { status =>'damaged' }
 387       if ( $item->damaged
 388         && !C4::Context->preference('AllowHoldsOnDamagedItems') );
 389
 390     # Check for the age restriction
 391     my ( $ageRestriction, $daysToAgeRestriction ) =
 392       C4::Circulation::GetAgeRestriction( $biblio->biblioitem->agerestriction, $borrower );
 393     return { status => 'ageRestricted' } if $daysToAgeRestriction && $daysToAgeRestriction > 0;
 394
 395     # Check that the patron doesn't have an item level hold on this item already
 396     return { status =>'itemAlreadyOnHold' }
 397       if ( !$params->{ignore_hold_counts} && Koha::Holds->search( { borrowernumber => $borrowernumber, itemnumber => $itemnumber } )->count() );
 398
 399     # Check that patron have not checked out this biblio (if AllowHoldsOnPatronsPossessions set)
 400     if ( !C4::Context->preference('AllowHoldsOnPatronsPossessions')
 401         && C4::Circulation::CheckIfIssuedToPatron( $patron->borrowernumber, $biblio->biblionumber ) ) {
 402         return { status =>'alreadypossession' };
 403     }
 404
 405     my $controlbranch = C4::Context->preference('ReservesControlBranch');
 406
 407     my $querycount = q{
 408         SELECT count(*) AS count
 409           FROM reserves
 410      LEFT JOIN items USING (itemnumber)
 411      LEFT JOIN biblioitems ON (reserves.biblionumber=biblioitems.biblionumber)
 412      LEFT JOIN borrowers USING (borrowernumber)
 413          WHERE borrowernumber = ?
 414     };
 415
 416     my $branchcode  = "";
 417     my $branchfield = "reserves.branchcode";
 418
 419     if ( $controlbranch eq "ItemHomeLibrary" ) {
 420         $branchfield = "items.homebranch";
 421         $branchcode  = $item->homebranch;
 422     }
 423     elsif ( $controlbranch eq "PatronLibrary" ) {
 424         $branchfield = "borrowers.branchcode";
 425         $branchcode  = $borrower->{branchcode};
 426     }
 427
 428     # we retrieve rights
 429     if (
 430         my $reservesallowed = Koha::CirculationRules->get_effective_rule({
 431                 itemtype     => $item->effective_itemtype,
 432                 categorycode => $borrower->{categorycode},
 433                 branchcode   => $branchcode,
 434                 rule_name    => 'reservesallowed',
 435         })
 436     ) {
 437         $ruleitemtype     = $reservesallowed->itemtype;
 438         $allowedreserves  = $reservesallowed->rule_value // 0; #undefined is 0, blank is unlimited
 439     }
 440     else {
 441         $ruleitemtype = undef;
 442     }
 443
 444     my $rights = Koha::CirculationRules->get_effective_rules({
 445         categorycode => $borrower->{'categorycode'},
 446         itemtype     => $item->effective_itemtype,
 447         branchcode   => $branchcode,
 448         rules        => ['holds_per_record','holds_per_day']
 449     });
 450     my $holds_per_record = $rights->{holds_per_record} // 1;
 451     my $holds_per_day    = $rights->{holds_per_day};
 452
 453     my $search_params = {
 454         borrowernumber => $borrowernumber,
 455         biblionumber   => $item->biblionumber,
 456     };
 457     $search_params->{found} = undef if $params->{ignore_found_holds};
 458
 459     my $holds = Koha::Holds->search($search_params);
 460     if (   defined $holds_per_record && $holds_per_record ne '' ){
 461         if ( $holds_per_record == 0 ) {
 462             return { status => "noReservesAllowed" };
 463         }
 464         if ( !$params->{ignore_hold_counts} && $holds->count() >= $holds_per_record ) {
 465             return { status => "tooManyHoldsForThisRecord", limit => $holds_per_record };
 466         }
 467     }
 468
 469     my $today_holds = Koha::Holds->search({
 470         borrowernumber => $borrowernumber,
 471         reservedate    => dt_from_string->date
 472     });
 473
 474     if (!$params->{ignore_hold_counts} && defined $holds_per_day && $holds_per_day ne ''
 475         && $today_holds->count() >= $holds_per_day )
 476     {
 477         return { status => 'tooManyReservesToday', limit => $holds_per_day };
 478     }
 479
 480     # we retrieve count
 481
 482     $querycount .= "AND ( $branchfield = ? OR $branchfield IS NULL )";
 483
 484     # If using item-level itypes, fall back to the record
 485     # level itemtype if the hold has no associated item
 486     $querycount .=
 487       C4::Context->preference('item-level_itypes')
 488       ? " AND COALESCE( items.itype, biblioitems.itemtype ) = ?"
 489       : " AND biblioitems.itemtype = ?"
 490       if defined $ruleitemtype;
 491
 492     my $sthcount = $dbh->prepare($querycount);
 493
 494     if ( defined $ruleitemtype ) {
 495         $sthcount->execute( $borrowernumber, $branchcode, $ruleitemtype );
 496     }
 497     else {
 498         $sthcount->execute( $borrowernumber, $branchcode );
 499     }
 500
 501     my $reservecount = "0";
 502     if ( my $rowcount = $sthcount->fetchrow_hashref() ) {
 503         $reservecount = $rowcount->{count};
 504     }
 505
 506     # we check if it's ok or not
 507     if ( defined $allowedreserves && $allowedreserves ne '' ){
 508         if( $allowedreserves == 0 ){
 509             return { status => 'noReservesAllowed' };
 510         }
 511         if ( !$params->{ignore_hold_counts} && $reservecount >= $allowedreserves ) {
 512             return { status => 'tooManyReserves', limit => $allowedreserves };
 513         }
 514     }
 515
 516     # Now we need to check hold limits by patron category
 517     my $rule = Koha::CirculationRules->get_effective_rule(
 518         {
 519             categorycode => $borrower->{categorycode},
 520             branchcode   => $branchcode,
 521             rule_name    => 'max_holds',
 522         }
 523     );
 524     if (!$params->{ignore_hold_counts} && $rule && defined( $rule->rule_value ) && $rule->rule_value ne '' ) {
 525         my $total_holds_count = Koha::Holds->search(
 526             {
 527                 borrowernumber => $borrower->{borrowernumber}
 528             }
 529         )->count();
 530
 531         return { status => 'tooManyReserves', limit => $rule->rule_value} if $total_holds_count >= $rule->rule_value;
 532     }
 533
 534     my $reserves_control_branch =
 535       GetReservesControlBranch( $item->unblessed(), $borrower );
 536     my $branchitemrule =
 537       C4::Circulation::GetBranchItemRule( $reserves_control_branch, $item->effective_itemtype );
 538
 539     if ( $branchitemrule->{holdallowed} eq 'not_allowed' ) {
 540         return { status => 'notReservable' };
 541     }
 542
 543     if (   $branchitemrule->{holdallowed} eq 'from_home_library'
 544         && $borrower->{branchcode} ne $item->homebranch )
 545     {
 546         return { status => 'cannotReserveFromOtherBranches' };
 547     }
 548
 549     my $item_library = Koha::Libraries->find( {branchcode => $item->homebranch} );
 550     if ( $branchitemrule->{holdallowed} eq 'from_local_hold_group') {
 551         if($borrower->{branchcode} ne $item->homebranch && !$item_library->validate_hold_sibling( {branchcode => $borrower->{branchcode}} )) {
 552             return { status => 'branchNotInHoldGroup' };
 553         }
 554     }
 555
 556     # If reservecount is ok, we check item branch if IndependentBranches is ON
 557     # and canreservefromotherbranches is OFF
 558     if ( C4::Context->preference('IndependentBranches')
 559         and !C4::Context->preference('canreservefromotherbranches') )
 560     {
 561         if ( $item->homebranch ne $borrower->{branchcode} ) {
 562             return { status => 'cannotReserveFromOtherBranches' };
 563         }
 564     }
 565
 566     if ($pickup_branchcode) {
 567         my $destination = Koha::Libraries->find({
 568             branchcode => $pickup_branchcode,
 569         });
 570
 571         unless ($destination) {
 572             return { status => 'libraryNotFound' };
 573         }
 574         unless ($destination->pickup_location) {
 575             return { status => 'libraryNotPickupLocation' };
 576         }
 577         unless ($item->can_be_transferred({ to => $destination })) {
 578             return { status => 'cannotBeTransferred' };
 579         }
 580         if ($branchitemrule->{hold_fulfillment_policy} eq 'holdgroup' && !$item_library->validate_hold_sibling( {branchcode => $pickup_branchcode} )) {
 581             return { status => 'pickupNotInHoldGroup' };
 582         }
 583         if ($branchitemrule->{hold_fulfillment_policy} eq 'patrongroup' && !Koha::Libraries->find({branchcode => $borrower->{branchcode}})->validate_hold_sibling({branchcode => $pickup_branchcode})) {
 584             return { status => 'pickupNotInHoldGroup' };
 585         }
 586     }
 587
 588     return { status => 'OK' };
 589 }
 590
 591 =head2 CanReserveBeCanceledFromOpac
 592
 593     $number = CanReserveBeCanceledFromOpac($reserve_id, $borrowernumber);
 594
 595     returns 1 if reserve can be cancelled by user from OPAC.
 596     First check if reserve belongs to user, next checks if reserve is not in
 597     transfer or waiting status
 598
 599 =cut
 600
 601 sub CanReserveBeCanceledFromOpac {
 602     my ($reserve_id, $borrowernumber) = @_;
 603
 604     return unless $reserve_id and $borrowernumber;
 605     my $reserve = Koha::Holds->find($reserve_id) or return;
 606
 607     return 0 unless $reserve->borrowernumber == $borrowernumber;
 608     return $reserve->is_cancelable_from_opac;
 609 }
 610
 611 =head2 GetOtherReserves
 612
 613   ($messages,$nextreservinfo)=$GetOtherReserves(itemnumber);
 614
 615 Check queued list of this document and check if this document must be transferred
 616
 617 =cut
 618
 619 sub GetOtherReserves {
 620     my ($itemnumber) = @_;
 621     my $messages;
 622     my $nextreservinfo;
 623     my ( undef, $checkreserves, undef ) = CheckReserves($itemnumber);
 624     if ($checkreserves) {
 625         my $item = Koha::Items->find($itemnumber);
 626         if ( $item->holdingbranch ne $checkreserves->{'branchcode'} ) {
 627             $messages->{'transfert'} = $checkreserves->{'branchcode'};
 628             #minus priorities of others reservs
 629             ModReserveMinusPriority(
 630                 $itemnumber,
 631                 $checkreserves->{'reserve_id'},
 632             );
 633
 634             #launch the subroutine dotransfer
 635             C4::Items::ModItemTransfer(
 636                 $itemnumber,
 637                 $item->holdingbranch,
 638                 $checkreserves->{'branchcode'},
 639                 'Reserve'
 640               ),
 641               ;
 642         }
 643
 644      #step 2b : case of a reservation on the same branch, set the waiting status
 645         else {
 646             $messages->{'waiting'} = 1;
 647             ModReserveMinusPriority(
 648                 $itemnumber,
 649                 $checkreserves->{'reserve_id'},
 650             );
 651             ModReserveStatus($itemnumber,'W');
 652         }
 653
 654         $nextreservinfo = $checkreserves;
 655     }
 656
 657     return ( $messages, $nextreservinfo );
 658 }
 659
 660 =head2 ChargeReserveFee
 661
 662     $fee = ChargeReserveFee( $borrowernumber, $fee, $title );
 663
 664     Charge the fee for a reserve (if $fee > 0)
 665
 666 =cut
 667
 668 sub ChargeReserveFee {
 669     my ( $borrowernumber, $fee, $title ) = @_;
 670     return if !$fee || $fee == 0;    # the last test is needed to include 0.00
 671     Koha::Account->new( { patron_id => $borrowernumber } )->add_debit(
 672         {
 673             amount       => $fee,
 674             description  => $title,
 675             note         => undef,
 676             user_id      => C4::Context->userenv ? C4::Context->userenv->{'number'} : undef,
 677             library_id   => C4::Context->userenv ? C4::Context->userenv->{'branch'} : undef,
 678             interface    => C4::Context->interface,
 679             invoice_type => undef,
 680             type         => 'RESERVE',
 681             item_id      => undef
 682         }
 683     );
 684 }
 685
 686 =head2 GetReserveFee
 687
 688     $fee = GetReserveFee( $borrowernumber, $biblionumber );
 689
 690     Calculate the fee for a reserve (if applicable).
 691
 692 =cut
 693
 694 sub GetReserveFee {
 695     my ( $borrowernumber, $biblionumber ) = @_;
 696     my $borquery = qq{
 697 SELECT reservefee FROM borrowers LEFT JOIN categories ON borrowers.categorycode = categories.categorycode WHERE borrowernumber = ?
 698     };
 699     my $issue_qry = qq{
 700 SELECT COUNT(*) FROM items
 701 LEFT JOIN issues USING (itemnumber)
 702 WHERE items.biblionumber=? AND issues.issue_id IS NULL
 703     };
 704     my $holds_qry = qq{
 705 SELECT COUNT(*) FROM reserves WHERE biblionumber=? AND borrowernumber<>?
 706     };
 707
 708     my $dbh = C4::Context->dbh;
 709     my ( $fee ) = $dbh->selectrow_array( $borquery, undef, ($borrowernumber) );
 710     my $hold_fee_mode = C4::Context->preference('HoldFeeMode') || 'not_always';
 711     if( $fee and $fee > 0 and $hold_fee_mode eq 'not_always' ) {
 712         # This is a reconstruction of the old code:
 713         # Compare number of items with items issued, and optionally check holds
 714         # If not all items are issued and there are no holds: charge no fee
 715         # NOTE: Lost, damaged, not-for-loan, etc. are just ignored here
 716         my ( $notissued, $reserved );
 717         ( $notissued ) = $dbh->selectrow_array( $issue_qry, undef,
 718             ( $biblionumber ) );
 719         if( $notissued ) {
 720             ( $reserved ) = $dbh->selectrow_array( $holds_qry, undef,
 721                 ( $biblionumber, $borrowernumber ) );
 722             $fee = 0 if $reserved == 0;
 723         }
 724     }
 725     return $fee;
 726 }
 727
 728 =head2 GetReserveStatus
 729
 730   $reservestatus = GetReserveStatus($itemnumber);
 731
 732 Takes an itemnumber and returns the status of the reserve placed on it.
 733 If several reserves exist, the reserve with the lower priority is given.
 734
 735 =cut
 736
 737 ## FIXME: I don't think this does what it thinks it does.
 738 ## It only ever checks the first reserve result, even though
 739 ## multiple reserves for that bib can have the itemnumber set
 740 ## the sub is only used once in the codebase.
 741 sub GetReserveStatus {
 742     my ($itemnumber) = @_;
 743
 744     my $dbh = C4::Context->dbh;
 745
 746     my ($sth, $found, $priority);
 747     if ( $itemnumber ) {
 748         $sth = $dbh->prepare("SELECT found, priority FROM reserves WHERE itemnumber = ? order by priority LIMIT 1");
 749         $sth->execute($itemnumber);
 750         ($found, $priority) = $sth->fetchrow_array;
 751     }
 752
 753     if(defined $found) {
 754         return 'Waiting'  if $found eq 'W' and $priority == 0;
 755         return 'Processing'  if $found eq 'P';
 756         return 'Finished' if $found eq 'F';
 757     }
 758
 759     return 'Reserved' if defined $priority && $priority > 0;
 760
 761     return ''; # empty string here will remove need for checking undef, or less log lines
 762 }
 763
 764 =head2 CheckReserves
 765
 766   ($status, $matched_reserve, $possible_reserves) = &CheckReserves($itemnumber);
 767   ($status, $matched_reserve, $possible_reserves) = &CheckReserves(undef, $barcode);
 768   ($status, $matched_reserve, $possible_reserves) = &CheckReserves($itemnumber,undef,$lookahead);
 769
 770 Find a book in the reserves.
 771
 772 C<$itemnumber> is the book's item number.
 773 C<$lookahead> is the number of days to look in advance for future reserves.
 774
 775 As I understand it, C<&CheckReserves> looks for the given item in the
 776 reserves. If it is found, that's a match, and C<$status> is set to
 777 C<Waiting>.
 778
 779 Otherwise, it finds the most important item in the reserves with the
 780 same biblio number as this book (I'm not clear on this) and returns it
 781 with C<$status> set to C<Reserved>.
 782
 783 C<&CheckReserves> returns a two-element list:
 784
 785 C<$status> is either C<Waiting>, C<Reserved> (see above), or 0.
 786
 787 C<$reserve> is the reserve item that matched. It is a
 788 reference-to-hash whose keys are mostly the fields of the reserves
 789 table in the Koha database.
 790
 791 =cut
 792
 793 sub CheckReserves {
 794     my ( $item, $barcode, $lookahead_days, $ignore_borrowers) = @_;
 795     my $dbh = C4::Context->dbh;
 796     my $sth;
 797     my $select;
 798     if (C4::Context->preference('item-level_itypes')){
 799         $select = "
 800            SELECT items.biblionumber,
 801            items.biblioitemnumber,
 802            itemtypes.notforloan,
 803            items.notforloan AS itemnotforloan,
 804            items.itemnumber,
 805            items.damaged,
 806            items.homebranch,
 807            items.holdingbranch
 808            FROM   items
 809            LEFT JOIN biblioitems ON items.biblioitemnumber = biblioitems.biblioitemnumber
 810            LEFT JOIN itemtypes   ON items.itype   = itemtypes.itemtype
 811         ";
 812     }
 813     else {
 814         $select = "
 815            SELECT items.biblionumber,
 816            items.biblioitemnumber,
 817            itemtypes.notforloan,
 818            items.notforloan AS itemnotforloan,
 819            items.itemnumber,
 820            items.damaged,
 821            items.homebranch,
 822            items.holdingbranch
 823            FROM   items
 824            LEFT JOIN biblioitems ON items.biblioitemnumber = biblioitems.biblioitemnumber
 825            LEFT JOIN itemtypes   ON biblioitems.itemtype   = itemtypes.itemtype
 826         ";
 827     }
 828
 829     if ($item) {
 830         $sth = $dbh->prepare("$select WHERE itemnumber = ?");
 831         $sth->execute($item);
 832     }
 833     else {
 834         $sth = $dbh->prepare("$select WHERE barcode = ?");
 835         $sth->execute($barcode);
 836     }
 837     # note: we get the itemnumber because we might have started w/ just the barcode.  Now we know for sure we have it.
 838     my ( $biblio, $bibitem, $notforloan_per_itemtype, $notforloan_per_item, $itemnumber, $damaged, $item_homebranch, $item_holdingbranch ) = $sth->fetchrow_array;
 839     return if ( $damaged && !C4::Context->preference('AllowHoldsOnDamagedItems') );
 840
 841     return unless $itemnumber; # bail if we got nothing.
 842     # if item is not for loan it cannot be reserved either.....
 843     # except where items.notforloan < 0 :  This indicates the item is holdable.
 844
 845     my @SkipHoldTrapOnNotForLoanValue = split( '\|', C4::Context->preference('SkipHoldTrapOnNotForLoanValue') );
 846     return if grep { $_ eq $notforloan_per_item } @SkipHoldTrapOnNotForLoanValue;
 847
 848     my $dont_trap = C4::Context->preference('TrapHoldsOnOrder') ? ($notforloan_per_item > 0) : ($notforloan_per_item && 1 );
 849     return if $dont_trap or $notforloan_per_itemtype;
 850
 851     # Find this item in the reserves
 852     my @reserves = _Findgroupreserve( $bibitem, $biblio, $itemnumber, $lookahead_days, $ignore_borrowers);
 853
 854     # $priority and $highest are used to find the most important item
 855     # in the list returned by &_Findgroupreserve. (The lower $priority,
 856     # the more important the item.)
 857     # $highest is the most important item we've seen so far.
 858     my $highest;
 859
 860     if (scalar @reserves) {
 861         my $LocalHoldsPriority = C4::Context->preference('LocalHoldsPriority');
 862         my $LocalHoldsPriorityPatronControl = C4::Context->preference('LocalHoldsPriorityPatronControl');
 863         my $LocalHoldsPriorityItemControl = C4::Context->preference('LocalHoldsPriorityItemControl');
 864
 865         my $priority = 10000000;
 866         foreach my $res (@reserves) {
 867             if ($res->{'found'} && $res->{'found'} eq 'W') {
 868                 return ( "Waiting", $res, \@reserves ); # Found it, it is waiting
 869             } elsif ($res->{'found'} && $res->{'found'} eq 'P') {
 870                 return ( "Processing", $res, \@reserves ); # Found determinated hold, e. g. the transferred one
 871             } elsif ($res->{'found'} && $res->{'found'} eq 'T') {
 872                 return ( "Transferred", $res, \@reserves ); # Found determinated hold, e. g. the transferred one
 873             } else {
 874                 my $patron;
 875                 my $item;
 876                 my $local_hold_match;
 877
 878                 if ($LocalHoldsPriority) {
 879                     $patron = Koha::Patrons->find( $res->{borrowernumber} );
 880                     $item = Koha::Items->find($itemnumber);
 881
 882                     unless ($item->exclude_from_local_holds_priority || $patron->category->exclude_from_local_holds_priority) {
 883                         my $local_holds_priority_item_branchcode =
 884                             $item->$LocalHoldsPriorityItemControl;
 885                         my $local_holds_priority_patron_branchcode =
 886                             ( $LocalHoldsPriorityPatronControl eq 'PickupLibrary' )
 887                             ? $res->{branchcode}
 888                             : ( $LocalHoldsPriorityPatronControl eq 'HomeLibrary' )
 889                             ? $patron->branchcode
 890                             : undef;
 891                         $local_hold_match =
 892                             $local_holds_priority_item_branchcode eq
 893                             $local_holds_priority_patron_branchcode;
 894                     }
 895                 }
 896
 897                 # See if this item is more important than what we've got so far
 898                 if ( ( $res->{'priority'} && $res->{'priority'} < $priority ) || $local_hold_match ) {
 899                     $item ||= Koha::Items->find($itemnumber);
 900                     next if $res->{itemtype} && $res->{itemtype} ne $item->effective_itemtype;
 901                     $patron ||= Koha::Patrons->find( $res->{borrowernumber} );
 902                     my $branch = GetReservesControlBranch( $item->unblessed, $patron->unblessed );
 903                     my $branchitemrule = C4::Circulation::GetBranchItemRule($branch,$item->effective_itemtype);
 904                     next if ($branchitemrule->{'holdallowed'} eq 'not_allowed');
 905                     next if (($branchitemrule->{'holdallowed'} eq 'from_home_library') && ($item->homebranch ne $patron->branchcode));
 906                     my $library = Koha::Libraries->find({branchcode=>$item->homebranch});
 907                     next if (($branchitemrule->{'holdallowed'} eq 'from_local_hold_group') && (!$library->validate_hold_sibling({branchcode => $patron->branchcode}) ));
 908                     my $hold_fulfillment_policy = $branchitemrule->{hold_fulfillment_policy};
 909                     next if ( ($hold_fulfillment_policy eq 'holdgroup') && (!$library->validate_hold_sibling({branchcode => $res->{branchcode}})) );
 910                     next if ( ($hold_fulfillment_policy eq 'homebranch') && ($res->{branchcode} ne $item->$hold_fulfillment_policy) );
 911                     next if ( ($hold_fulfillment_policy eq 'holdingbranch') && ($res->{branchcode} ne $item->$hold_fulfillment_policy) );
 912                     next unless $item->can_be_transferred( { to => Koha::Libraries->find( $res->{branchcode} ) } );
 913                     $priority = $res->{'priority'};
 914                     $highest  = $res;
 915                     last if $local_hold_match;
 916                 }
 917             }
 918         }
 919     }
 920
 921     # If we get this far, then no exact match was found.
 922     # We return the most important (i.e. next) reservation.
 923     if ($highest) {
 924         $highest->{'itemnumber'} = $item;
 925         return ( "Reserved", $highest, \@reserves );
 926     }
 927
 928     return ( '' );
 929 }
 930
 931 =head2 CancelExpiredReserves
 932
 933   CancelExpiredReserves();
 934
 935 Cancels all reserves with an expiration date from before today.
 936
 937 =cut
 938
 939 sub CancelExpiredReserves {
 940     my $cancellation_reason = shift;
 941     my $today = dt_from_string();
 942     my $cancel_on_holidays = C4::Context->preference('ExpireReservesOnHolidays');
 943     my $expireWaiting = C4::Context->preference('ExpireReservesMaxPickUpDelay');
 944
 945     my $dtf = Koha::Database->new->schema->storage->datetime_parser;
 946     my $params = { expirationdate => { '<', $dtf->format_date($today) } };
 947     $params->{found} = [ { '!=', 'W' }, undef ]  unless $expireWaiting;
 948
 949     # FIXME To move to Koha::Holds->search_expired (?)
 950     my $holds = Koha::Holds->search( $params );
 951
 952     while ( my $hold = $holds->next ) {
 953         my $calendar = Koha::Calendar->new( branchcode => $hold->branchcode );
 954
 955         next if !$cancel_on_holidays && $calendar->is_holiday( $today );
 956
 957         my $cancel_params = {};
 958         $cancel_params->{cancellation_reason} = $cancellation_reason if defined($cancellation_reason);
 959         if ( defined($hold->found) && $hold->found eq 'W' ) {
 960             $cancel_params->{charge_cancel_fee} = 1;
 961         }
 962         $hold->cancel( $cancel_params );
 963     }
 964 }
 965
 966 =head2 AutoUnsuspendReserves
 967
 968   AutoUnsuspendReserves();
 969
 970 Unsuspends all suspended reserves with a suspend_until date from before today.
 971
 972 =cut
 973
 974 sub AutoUnsuspendReserves {
 975     my $today = dt_from_string();
 976
 977     my @holds = Koha::Holds->search( { suspend_until => { '<=' => $today->ymd() } } );
 978
 979     map { $_->resume() } @holds;
 980 }
 981
 982 =head2 ModReserve
 983
 984   ModReserve({ rank => $rank,
 985                reserve_id => $reserve_id,
 986                branchcode => $branchcode
 987                [, itemnumber => $itemnumber ]
 988                [, biblionumber => $biblionumber, $borrowernumber => $borrowernumber ]
 989               });
 990
 991 Change a hold request's priority or cancel it.
 992
 993 C<$rank> specifies the effect of the change.  If C<$rank>
 994 is 'W' or 'n', nothing happens.  This corresponds to leaving a
 995 request alone when changing its priority in the holds queue
 996 for a bib.
 997
 998 If C<$rank> is 'del', the hold request is cancelled.
 999
1000 If C<$rank> is an integer greater than zero, the priority of
1001 the request is set to that value.  Since priority != 0 means
1002 that the item is not waiting on the hold shelf, setting the
1003 priority to a non-zero value also sets the request's found
1004 status and waiting date to NULL.
1005
1006 The optional C<$itemnumber> parameter is used only when
1007 C<$rank> is a non-zero integer; if supplied, the itemnumber
1008 of the hold request is set accordingly; if omitted, the itemnumber
1009 is cleared.
1010
1011 B<FIXME:> Note that the forgoing can have the effect of causing
1012 item-level hold requests to turn into title-level requests.  This
1013 will be fixed once reserves has separate columns for requested
1014 itemnumber and supplying itemnumber.
1015
1016 =cut
1017
1018 sub ModReserve {
1019     my ( $params ) = @_;
1020
1021     my $rank = $params->{'rank'};
1022     my $reserve_id = $params->{'reserve_id'};
1023     my $branchcode = $params->{'branchcode'};
1024     my $itemnumber = $params->{'itemnumber'};
1025     my $suspend_until = $params->{'suspend_until'};
1026     my $borrowernumber = $params->{'borrowernumber'};
1027     my $biblionumber = $params->{'biblionumber'};
1028     my $cancellation_reason = $params->{'cancellation_reason'};
1029
1030     return if $rank eq "n";
1031
1032     return unless ( $reserve_id || ( $borrowernumber && ( $biblionumber || $itemnumber ) ) );
1033
1034     my $hold;
1035     unless ( $reserve_id ) {
1036         my $holds = Koha::Holds->search({ biblionumber => $biblionumber, borrowernumber => $borrowernumber, itemnumber => $itemnumber });
1037         return unless $holds->count; # FIXME Should raise an exception
1038         $hold = $holds->next;
1039         $reserve_id = $hold->reserve_id;
1040     }
1041
1042     $hold ||= Koha::Holds->find($reserve_id);
1043
1044     if ( $rank eq "del" ) {
1045         $hold->cancel({ cancellation_reason => $cancellation_reason });
1046     }
1047     elsif ($hold->found && $hold->priority eq '0') {
1048         logaction( 'HOLDS', 'MODIFY', $hold->reserve_id, Dumper($hold->unblessed) )
1049             if C4::Context->preference('HoldsLog');
1050
1051         # The only column that can be updated for a found hold is the expiration date
1052         my $date = $params->{expirationdate};
1053         if ($date) {
1054             $hold->expirationdate(dt_from_string($date))->store();
1055         }
1056     }
1057     elsif ($rank =~ /^\d+/ and $rank > 0) {
1058         logaction( 'HOLDS', 'MODIFY', $hold->reserve_id, Dumper($hold->unblessed) )
1059             if C4::Context->preference('HoldsLog');
1060
1061         my $properties = {
1062             priority    => $rank,
1063             branchcode  => $branchcode,
1064             itemnumber  => $itemnumber,
1065             found       => undef,
1066             waitingdate => undef
1067         };
1068         if (exists $params->{reservedate}) {
1069             $properties->{reservedate} = $params->{reservedate} || undef;
1070         }
1071         if (exists $params->{expirationdate}) {
1072             $properties->{expirationdate} = $params->{expirationdate} || undef;
1073         }
1074
1075         $hold->set($properties)->store();
1076
1077         if ( defined( $suspend_until ) ) {
1078             if ( $suspend_until ) {
1079                 $suspend_until = eval { dt_from_string( $suspend_until ) };
1080                 $hold->suspend_hold( $suspend_until );
1081             } else {
1082                 # If the hold is suspended leave the hold suspended, but convert it to an indefinite hold.
1083                 # If the hold is not suspended, this does nothing.
1084                 $hold->set( { suspend_until => undef } )->store();
1085             }
1086         }
1087
1088         _FixPriority({ reserve_id => $reserve_id, rank =>$rank });
1089     }
1090 }
1091
1092 =head2 ModReserveFill
1093
1094   &ModReserveFill($reserve);
1095
1096 Fill a reserve. If I understand this correctly, this means that the
1097 reserved book has been found and given to the patron who reserved it.
1098
1099 C<$reserve> specifies the reserve to fill. It is a reference-to-hash
1100 whose keys are fields from the reserves table in the Koha database.
1101
1102 =cut
1103
1104 sub ModReserveFill {
1105     my ($res) = @_;
1106     my $reserve_id = $res->{'reserve_id'};
1107
1108     my $hold = Koha::Holds->find($reserve_id);
1109     # get the priority on this record....
1110     my $priority = $hold->priority;
1111
1112     # update the hold statuses, no need to store it though, we will be deleting it anyway
1113     $hold->set(
1114         {
1115             found    => 'F',
1116             priority => 0,
1117         }
1118     );
1119
1120     logaction( 'HOLDS', 'MODIFY', $hold->reserve_id, Dumper($hold->unblessed) )
1121         if C4::Context->preference('HoldsLog');
1122
1123     # FIXME Must call Koha::Hold->cancel ? => No, should call ->filled and add the correct log
1124     Koha::Old::Hold->new( $hold->unblessed() )->store();
1125
1126     $hold->delete();
1127
1128     if ( C4::Context->preference('HoldFeeMode') eq 'any_time_is_collected' ) {
1129         my $reserve_fee = GetReserveFee( $hold->borrowernumber, $hold->biblionumber );
1130         ChargeReserveFee( $hold->borrowernumber, $reserve_fee, $hold->biblio->title );
1131     }
1132
1133     # now fix the priority on the others (if the priority wasn't
1134     # already sorted!)....
1135     unless ( $priority == 0 ) {
1136         _FixPriority( { reserve_id => $reserve_id, biblionumber => $hold->biblionumber } );
1137     }
1138 }
1139
1140 =head2 ModReserveStatus
1141
1142   &ModReserveStatus($itemnumber, $newstatus);
1143
1144 Update the reserve status for the active (priority=0) reserve.
1145
1146 $itemnumber is the itemnumber the reserve is on
1147
1148 $newstatus is the new status.
1149
1150 =cut
1151
1152 sub ModReserveStatus {
1153
1154     #first : check if we have a reservation for this item .
1155     my ($itemnumber, $newstatus) = @_;
1156     my $dbh = C4::Context->dbh;
1157
1158     my $query = "UPDATE reserves SET found = ?, waitingdate = NOW() WHERE itemnumber = ? AND found IS NULL AND priority = 0";
1159     my $sth_set = $dbh->prepare($query);
1160     $sth_set->execute( $newstatus, $itemnumber );
1161
1162     my $item = Koha::Items->find($itemnumber);
1163     if ( $item->location && $item->location eq 'CART'
1164         && ( !$item->permanent_location || $item->permanent_location ne 'CART' )
1165         && $newstatus ) {
1166       CartToShelf( $itemnumber );
1167     }
1168 }
1169
1170 =head2 ModReserveAffect
1171
1172   &ModReserveAffect($itemnumber,$borrowernumber,$diffBranchSend,$reserve_id, $desk_id);
1173
1174 This function affect an item and a status for a given reserve, either fetched directly
1175 by record_id, or by borrowernumber and itemnumber or biblionumber. If only biblionumber
1176 is given, only first reserve returned is affected, which is ok for anything but
1177 multi-item holds.
1178
1179 if $transferToDo is not set, then the status is set to "Waiting" as well.
1180 otherwise, a transfer is on the way, and the end of the transfer will
1181 take care of the waiting status
1182
1183 This function also removes any entry of the hold in holds queue table.
1184
1185 =cut
1186
1187 sub ModReserveAffect {
1188     my ( $itemnumber, $borrowernumber, $transferToDo, $reserve_id, $desk_id ) = @_;
1189     my $dbh = C4::Context->dbh;
1190
1191     # we want to attach $itemnumber to $borrowernumber, find the biblionumber
1192     # attached to $itemnumber
1193     my $sth = $dbh->prepare("SELECT biblionumber FROM items WHERE itemnumber=?");
1194     $sth->execute($itemnumber);
1195     my ($biblionumber) = $sth->fetchrow;
1196
1197     # get request - need to find out if item is already
1198     # waiting in order to not send duplicate hold filled notifications
1199
1200     my $hold;
1201     # Find hold by id if we have it
1202     $hold = Koha::Holds->find( $reserve_id ) if $reserve_id;
1203     # Find item level hold for this item if there is one
1204     $hold ||= Koha::Holds->search( { borrowernumber => $borrowernumber, itemnumber => $itemnumber } )->next();
1205     # Find record level hold if there is no item level hold
1206     $hold ||= Koha::Holds->search( { borrowernumber => $borrowernumber, biblionumber => $biblionumber } )->next();
1207
1208     return unless $hold;
1209
1210     my $already_on_shelf = $hold->found && $hold->found eq 'W';
1211
1212     $hold->itemnumber($itemnumber);
1213
1214     if ($transferToDo) {
1215         $hold->set_transfer();
1216     } elsif (C4::Context->preference('HoldsNeedProcessingSIP')
1217              && C4::Context->interface eq 'sip'
1218              && !$already_on_shelf) {
1219         $hold->set_processing();
1220     } else {
1221         $hold->set_waiting($desk_id);
1222         _koha_notify_reserve( $hold->reserve_id ) unless $already_on_shelf;
1223         # Complete transfer if one exists
1224         my $transfer = $hold->item->get_transfer;
1225         $transfer->receive if $transfer;
1226     }
1227
1228     _FixPriority( { biblionumber => $biblionumber } );
1229     my $item = Koha::Items->find($itemnumber);
1230     if ( $item->location && $item->location eq 'CART'
1231         && ( !$item->permanent_location || $item->permanent_location ne 'CART' ) ) {
1232       CartToShelf( $itemnumber );
1233     }
1234
1235     my $std = $dbh->prepare(q{
1236         DELETE  q, t
1237         FROM    tmp_holdsqueue q
1238         INNER JOIN hold_fill_targets t
1239         ON  q.borrowernumber = t.borrowernumber
1240             AND q.biblionumber = t.biblionumber
1241             AND q.itemnumber = t.itemnumber
1242             AND q.item_level_request = t.item_level_request
1243             AND q.holdingbranch = t.source_branchcode
1244         WHERE t.reserve_id = ?
1245     });
1246     $std->execute($hold->reserve_id);
1247
1248     logaction( 'HOLDS', 'MODIFY', $hold->reserve_id, Dumper($hold->get_from_storage->unblessed) )
1249         if C4::Context->preference('HoldsLog');
1250
1251     return;
1252 }
1253
1254 =head2 ModReserveCancelAll
1255
1256   ($messages,$nextreservinfo) = &ModReserveCancelAll($itemnumber,$borrowernumber,$reason);
1257
1258 function to cancel reserv,check other reserves, and transfer document if it's necessary
1259
1260 =cut
1261
1262 sub ModReserveCancelAll {
1263     my $messages;
1264     my $nextreservinfo;
1265     my ( $itemnumber, $borrowernumber, $cancellation_reason ) = @_;
1266
1267     #step 1 : cancel the reservation
1268     my $holds = Koha::Holds->search({ itemnumber => $itemnumber, borrowernumber => $borrowernumber });
1269     return unless $holds->count;
1270     $holds->next->cancel({ cancellation_reason => $cancellation_reason });
1271
1272     #step 2 launch the subroutine of the others reserves
1273     ( $messages, $nextreservinfo ) = GetOtherReserves($itemnumber);
1274
1275     return ( $messages, $nextreservinfo->{borrowernumber} );
1276 }
1277
1278 =head2 ModReserveMinusPriority
1279
1280   &ModReserveMinusPriority($itemnumber,$borrowernumber,$biblionumber)
1281
1282 Reduce the values of queued list
1283
1284 =cut
1285
1286 sub ModReserveMinusPriority {
1287     my ( $itemnumber, $reserve_id ) = @_;
1288
1289     #first step update the value of the first person on reserv
1290     my $dbh   = C4::Context->dbh;
1291     my $query = "
1292         UPDATE reserves
1293         SET    priority = 0 , itemnumber = ?
1294         WHERE  reserve_id = ?
1295     ";
1296     my $sth_upd = $dbh->prepare($query);
1297     $sth_upd->execute( $itemnumber, $reserve_id );
1298     # second step update all others reserves
1299     _FixPriority({ reserve_id => $reserve_id, rank => '0' });
1300 }
1301
1302 =head2 IsAvailableForItemLevelRequest
1303
1304   my $is_available = IsAvailableForItemLevelRequest( $item_record, $borrower_record, $pickup_branchcode );
1305
1306 Checks whether a given item record is available for an
1307 item-level hold request.  An item is available if
1308
1309 * it is not lost AND
1310 * it is not damaged AND
1311 * it is not withdrawn AND
1312 * a waiting or in transit reserve is placed on
1313 * does not have a not for loan value > 0
1314
1315 Need to check the issuingrules onshelfholds column,
1316 if this is set items on the shelf can be placed on hold
1317
1318 Note that IsAvailableForItemLevelRequest() does not
1319 check if the staff operator is authorized to place
1320 a request on the item - in particular,
1321 this routine does not check IndependentBranches
1322 and canreservefromotherbranches.
1323
1324 Note also that this subroutine does not checks smart
1325 rules limits for item by reservesallowed/holds_per_record
1326 values, this complemented in calling code with calls and
1327 checks with CanItemBeReserved or CanBookBeReserved.
1328
1329 =cut
1330
1331 sub IsAvailableForItemLevelRequest {
1332     my $item                = shift;
1333     my $patron              = shift;
1334     my $pickup_branchcode   = shift;
1335     # items_any_available is precalculated status passed from request.pl when set of items
1336     # looped outside of IsAvailableForItemLevelRequest to avoid nested loops:
1337     my $items_any_available = shift;
1338
1339     my $dbh = C4::Context->dbh;
1340     # must check the notforloan setting of the itemtype
1341     # FIXME - a lot of places in the code do this
1342     #         or something similar - need to be
1343     #         consolidated
1344     my $itemtype = $item->effective_itemtype;
1345     my $notforloan_per_itemtype = Koha::ItemTypes->find($itemtype)->notforloan;
1346
1347     return 0 if
1348         $notforloan_per_itemtype ||
1349         $item->itemlost        ||
1350         $item->notforloan > 0  || # item with negative or zero notforloan value is holdable
1351         $item->withdrawn        ||
1352         ($item->damaged && !C4::Context->preference('AllowHoldsOnDamagedItems'));
1353
1354     if ($pickup_branchcode) {
1355         my $destination = Koha::Libraries->find($pickup_branchcode);
1356         return 0 unless $destination;
1357         return 0 unless $destination->pickup_location;
1358         return 0 unless $item->can_be_transferred( { to => $destination } );
1359         my $reserves_control_branch =
1360             GetReservesControlBranch( $item->unblessed(), $patron->unblessed() );
1361         my $branchitemrule =
1362             C4::Circulation::GetBranchItemRule( $reserves_control_branch, $item->itype );
1363         my $home_library = Koha::Libraries->find( {branchcode => $item->homebranch} );
1364         return 0 unless $branchitemrule->{hold_fulfillment_policy} ne 'holdgroup' || $home_library->validate_hold_sibling( {branchcode => $pickup_branchcode} );
1365     }
1366
1367     my $on_shelf_holds = Koha::CirculationRules->get_onshelfholds_policy( { item => $item, patron => $patron } );
1368
1369     if ( $on_shelf_holds == 1 ) {
1370         return 1;
1371     } elsif ( $on_shelf_holds == 2 ) {
1372
1373         # if we have this param predefined from outer caller sub, we just need
1374         # to return it, so we saving from having loop inside other loop:
1375         return  $items_any_available ? 0 : 1
1376             if defined $items_any_available;
1377
1378         my $any_available = ItemsAnyAvailableAndNotRestricted( { biblionumber => $item->biblionumber, patron => $patron });
1379         return $any_available ? 0 : 1;
1380     } else { # on_shelf_holds == 0 "If any unavailable" (the description is rather cryptic and could still be improved)
1381         return $item->onloan || IsItemOnHoldAndFound( $item->itemnumber );
1382     }
1383 }
1384
1385 =head2 ItemsAnyAvailableAndNotRestricted
1386
1387   ItemsAnyAvailableAndNotRestricted( { biblionumber => $biblionumber, patron => $patron });
1388
1389 This function checks all items for specified biblionumber (numeric) against patron (object)
1390 and returns true (1) if at least one item available for loan/check out/present/not held
1391 and also checks other parameters logic which not restricts item for hold at all (for ex.
1392 AllowHoldsOnDamagedItems or 'holdallowed' own/sibling library)
1393
1394 =cut
1395
1396 sub ItemsAnyAvailableAndNotRestricted {
1397     my $param = shift;
1398
1399     my @items = Koha::Items->search( { biblionumber => $param->{biblionumber} } );
1400
1401     foreach my $i (@items) {
1402         my $reserves_control_branch =
1403             GetReservesControlBranch( $i->unblessed(), $param->{patron}->unblessed );
1404         my $branchitemrule =
1405             C4::Circulation::GetBranchItemRule( $reserves_control_branch, $i->itype );
1406         my $item_library = Koha::Libraries->find( { branchcode => $i->homebranch } );
1407
1408         # we can return (end the loop) when first one found:
1409         return 1
1410             unless $i->itemlost
1411             || $i->notforloan # items with non-zero notforloan cannot be checked out
1412             || $i->withdrawn
1413             || $i->onloan
1414             || IsItemOnHoldAndFound( $i->id )
1415             || ( $i->damaged
1416                  && ! C4::Context->preference('AllowHoldsOnDamagedItems') )
1417             || Koha::ItemTypes->find( $i->effective_itemtype() )->notforloan
1418             || $branchitemrule->{holdallowed} eq 'from_home_library' && $param->{patron}->branchcode ne $i->homebranch
1419             || $branchitemrule->{holdallowed} eq 'from_local_hold_group' && ! $item_library->validate_hold_sibling( { branchcode => $param->{patron}->branchcode } )
1420             || CanItemBeReserved( $param->{patron}->borrowernumber, $i->id )->{status} ne 'OK';
1421     }
1422
1423     return 0;
1424 }
1425
1426 =head2 AlterPriority
1427
1428   AlterPriority( $where, $reserve_id, $prev_priority, $next_priority, $first_priority, $last_priority );
1429
1430 This function changes a reserve's priority up, down, to the top, or to the bottom.
1431 Input: $where is 'up', 'down', 'top' or 'bottom'. Biblionumber, Date reserve was placed
1432
1433 =cut
1434
1435 sub AlterPriority {
1436     my ( $where, $reserve_id, $prev_priority, $next_priority, $first_priority, $last_priority ) = @_;
1437
1438     my $hold = Koha::Holds->find( $reserve_id );
1439     return unless $hold;
1440
1441     if ( $hold->cancellationdate ) {
1442         warn "I cannot alter the priority for reserve_id $reserve_id, the reserve has been cancelled (" . $hold->cancellationdate . ')';
1443         return;
1444     }
1445
1446     if ( $where eq 'up' ) {
1447       return unless $prev_priority;
1448       _FixPriority({ reserve_id => $reserve_id, rank => $prev_priority })
1449     } elsif ( $where eq 'down' ) {
1450       return unless $next_priority;
1451       _FixPriority({ reserve_id => $reserve_id, rank => $next_priority })
1452     } elsif ( $where eq 'top' ) {
1453       _FixPriority({ reserve_id => $reserve_id, rank => $first_priority })
1454     } elsif ( $where eq 'bottom' ) {
1455       _FixPriority({ reserve_id => $reserve_id, rank => $last_priority });
1456     }
1457
1458     # FIXME Should return the new priority
1459 }
1460
1461 =head2 ToggleLowestPriority
1462
1463   ToggleLowestPriority( $borrowernumber, $biblionumber );
1464
1465 This function sets the lowestPriority field to true if is false, and false if it is true.
1466
1467 =cut
1468
1469 sub ToggleLowestPriority {
1470     my ( $reserve_id ) = @_;
1471
1472     my $dbh = C4::Context->dbh;
1473
1474     my $sth = $dbh->prepare( "UPDATE reserves SET lowestPriority = NOT lowestPriority WHERE reserve_id = ?");
1475     $sth->execute( $reserve_id );
1476
1477     _FixPriority({ reserve_id => $reserve_id, rank => '999999' });
1478 }
1479
1480 =head2 ToggleSuspend
1481
1482   ToggleSuspend( $reserve_id );
1483
1484 This function sets the suspend field to true if is false, and false if it is true.
1485 If the reserve is currently suspended with a suspend_until date, that date will
1486 be cleared when it is unsuspended.
1487
1488 =cut
1489
1490 sub ToggleSuspend {
1491     my ( $reserve_id, $suspend_until ) = @_;
1492
1493     $suspend_until = dt_from_string($suspend_until) if ($suspend_until);
1494
1495     my $hold = Koha::Holds->find( $reserve_id );
1496
1497     if ( $hold->is_suspended ) {
1498         $hold->resume()
1499     } else {
1500         $hold->suspend_hold( $suspend_until );
1501     }
1502 }
1503
1504 =head2 SuspendAll
1505
1506   SuspendAll(
1507       borrowernumber   => $borrowernumber,
1508       [ biblionumber   => $biblionumber, ]
1509       [ suspend_until  => $suspend_until, ]
1510       [ suspend        => $suspend ]
1511   );
1512
1513   This function accepts a set of hash keys as its parameters.
1514   It requires either borrowernumber or biblionumber, or both.
1515
1516   suspend_until is wholly optional.
1517
1518 =cut
1519
1520 sub SuspendAll {
1521     my %params = @_;
1522
1523     my $borrowernumber = $params{'borrowernumber'} || undef;
1524     my $biblionumber   = $params{'biblionumber'}   || undef;
1525     my $suspend_until  = $params{'suspend_until'}  || undef;
1526     my $suspend = defined( $params{'suspend'} ) ? $params{'suspend'} : 1;
1527
1528     $suspend_until = eval { dt_from_string($suspend_until) }
1529       if ( defined($suspend_until) );
1530
1531     return unless ( $borrowernumber || $biblionumber );
1532
1533     my $params;
1534     $params->{found}          = undef;
1535     $params->{borrowernumber} = $borrowernumber if $borrowernumber;
1536     $params->{biblionumber}   = $biblionumber if $biblionumber;
1537
1538     my @holds = Koha::Holds->search($params);
1539
1540     if ($suspend) {
1541         map { $_->suspend_hold($suspend_until) } @holds;
1542     }
1543     else {
1544         map { $_->resume() } @holds;
1545     }
1546 }
1547
1548
1549 =head2 _FixPriority
1550
1551   _FixPriority({
1552     reserve_id => $reserve_id,
1553     [rank => $rank,]
1554     [ignoreSetLowestRank => $ignoreSetLowestRank]
1555   });
1556
1557   or
1558
1559   _FixPriority({ biblionumber => $biblionumber});
1560
1561 This routine adjusts the priority of a hold request and holds
1562 on the same bib.
1563
1564 In the first form, where a reserve_id is passed, the priority of the
1565 hold is set to supplied rank, and other holds for that bib are adjusted
1566 accordingly.  If the rank is "del", the hold is cancelled.  If no rank
1567 is supplied, all of the holds on that bib have their priority adjusted
1568 as if the second form had been used.
1569
1570 In the second form, where a biblionumber is passed, the holds on that
1571 bib (that are not captured) are sorted in order of increasing priority,
1572 then have reserves.priority set so that the first non-captured hold
1573 has its priority set to 1, the second non-captured hold has its priority
1574 set to 2, and so forth.
1575
1576 In both cases, holds that have the lowestPriority flag on are have their
1577 priority adjusted to ensure that they remain at the end of the line.
1578
1579 Note that the ignoreSetLowestRank parameter is meant to be used only
1580 when _FixPriority calls itself.
1581
1582 =cut
1583
1584 sub _FixPriority {
1585     my ( $params ) = @_;
1586     my $reserve_id = $params->{reserve_id};
1587     my $rank = $params->{rank} // '';
1588     my $ignoreSetLowestRank = $params->{ignoreSetLowestRank};
1589     my $biblionumber = $params->{biblionumber};
1590
1591     my $dbh = C4::Context->dbh;
1592
1593     my $hold;
1594     if ( $reserve_id ) {
1595         $hold = Koha::Holds->find( $reserve_id );
1596         if (!defined $hold){
1597             # may have already been checked out and hold fulfilled
1598             $hold = Koha::Old::Holds->find( $reserve_id );
1599         }
1600         return unless $hold;
1601     }
1602
1603     unless ( $biblionumber ) { # FIXME This is a very weird API
1604         $biblionumber = $hold->biblionumber;
1605     }
1606
1607     if ( $rank eq "del" ) { # FIXME will crash if called without $hold
1608         $hold->cancel;
1609     }
1610     elsif ( $reserve_id && ( $rank eq "W" || $rank eq "0" ) ) {
1611
1612         # make sure priority for waiting or in-transit items is 0
1613         my $query = "
1614             UPDATE reserves
1615             SET    priority = 0
1616             WHERE reserve_id = ?
1617             AND found IN ('W', 'T', 'P')
1618         ";
1619         my $sth = $dbh->prepare($query);
1620         $sth->execute( $reserve_id );
1621     }
1622     my @priority;
1623
1624     # get whats left
1625     my $query = "
1626         SELECT reserve_id, borrowernumber, reservedate
1627         FROM   reserves
1628         WHERE  biblionumber   = ?
1629           AND  ((found <> 'W' AND found <> 'T' AND found <> 'P') OR found IS NULL)
1630         ORDER BY priority ASC
1631     ";
1632     my $sth = $dbh->prepare($query);
1633     $sth->execute( $biblionumber );
1634     while ( my $line = $sth->fetchrow_hashref ) {
1635         push( @priority,     $line );
1636     }
1637
1638     # FIXME This whole sub must be rewritten, especially to highlight what is done when reserve_id is not given
1639     # To find the matching index
1640     my $i;
1641     my $key = -1;    # to allow for 0 to be a valid result
1642     for ( $i = 0 ; $i < @priority ; $i++ ) {
1643         if ( $reserve_id && $reserve_id == $priority[$i]->{'reserve_id'} ) {
1644             $key = $i;    # save the index
1645             last;
1646         }
1647     }
1648
1649     # if index exists in array then move it to new position
1650     if ( $key > -1 && $rank ne 'del' && $rank > 0 ) {
1651         my $new_rank = $rank - 1; # $new_rank is what you want the new index to be in the array
1652         my $moving_item = splice( @priority, $key, 1 );
1653         $new_rank = scalar @priority if $new_rank > scalar @priority;
1654         splice( @priority, $new_rank, 0, $moving_item );
1655     }
1656
1657     # now fix the priority on those that are left....
1658     $query = "
1659         UPDATE reserves
1660         SET    priority = ?
1661         WHERE  reserve_id = ?
1662     ";
1663     $sth = $dbh->prepare($query);
1664     for ( my $j = 0 ; $j < @priority ; $j++ ) {
1665         $sth->execute(
1666             $j + 1,
1667             $priority[$j]->{'reserve_id'}
1668         );
1669     }
1670
1671     unless ( $ignoreSetLowestRank ) {
1672         $sth = $dbh->prepare( "SELECT reserve_id FROM reserves WHERE lowestPriority = 1 AND biblionumber = ? ORDER BY priority" );
1673         $sth->execute($biblionumber);
1674       while ( my $res = $sth->fetchrow_hashref() ) {
1675         _FixPriority({
1676             reserve_id => $res->{'reserve_id'},
1677             rank => '999999',
1678             ignoreSetLowestRank => 1
1679         });
1680       }
1681     }
1682 }
1683
1684 =head2 _Findgroupreserve
1685
1686   @results = &_Findgroupreserve($biblioitemnumber, $biblionumber, $itemnumber, $lookahead, $ignore_borrowers);
1687
1688 Looks for a holds-queue based item-specific match first, then for a holds-queue title-level match, returning the
1689 first match found.  If neither, then we look for non-holds-queue based holds.
1690 Lookahead is the number of days to look in advance.
1691
1692 C<&_Findgroupreserve> returns :
1693 C<@results> is an array of references-to-hash whose keys are mostly
1694 fields from the reserves table of the Koha database, plus
1695 C<biblioitemnumber>.
1696
1697 This routine with either return:
1698 1 - Item specific holds from the holds queue
1699 2 - Title level holds from the holds queue
1700 3 - All holds for this biblionumber
1701
1702 All return values will respect any borrowernumbers passed as arrayref in $ignore_borrowers
1703
1704 =cut
1705
1706 sub _Findgroupreserve {
1707     my ( $bibitem, $biblio, $itemnumber, $lookahead, $ignore_borrowers) = @_;
1708     my $dbh   = C4::Context->dbh;
1709
1710     # TODO: consolidate at least the SELECT portion of the first 2 queries to a common $select var.
1711     # check for exact targeted match
1712     my $item_level_target_query = qq{
1713         SELECT reserves.biblionumber        AS biblionumber,
1714                reserves.borrowernumber      AS borrowernumber,
1715                reserves.reservedate         AS reservedate,
1716                reserves.branchcode          AS branchcode,
1717                reserves.cancellationdate    AS cancellationdate,
1718                reserves.found               AS found,
1719                reserves.reservenotes        AS reservenotes,
1720                reserves.priority            AS priority,
1721                reserves.timestamp           AS timestamp,
1722                biblioitems.biblioitemnumber AS biblioitemnumber,
1723                reserves.itemnumber          AS itemnumber,
1724                reserves.reserve_id          AS reserve_id,
1725                reserves.itemtype            AS itemtype,
1726                reserves.non_priority        AS non_priority
1727         FROM reserves
1728         JOIN biblioitems USING (biblionumber)
1729         JOIN hold_fill_targets USING (reserve_id)
1730         WHERE found IS NULL
1731         AND priority > 0
1732         AND item_level_request = 1
1733         AND hold_fill_targets.itemnumber = ?
1734         AND reservedate <= DATE_ADD(NOW(),INTERVAL ? DAY)
1735         AND suspend = 0
1736         ORDER BY priority
1737     };
1738     my $sth = $dbh->prepare($item_level_target_query);
1739     $sth->execute($itemnumber, $lookahead||0);
1740     my @results;
1741     if ( my $data = $sth->fetchrow_hashref ) {
1742         push( @results, $data )
1743           unless any{ $data->{borrowernumber} eq $_ } @$ignore_borrowers ;
1744     }
1745     return @results if @results;
1746
1747     # check for title-level targeted match
1748     my $title_level_target_query = qq{
1749         SELECT reserves.biblionumber        AS biblionumber,
1750                reserves.borrowernumber      AS borrowernumber,
1751                reserves.reservedate         AS reservedate,
1752                reserves.branchcode          AS branchcode,
1753                reserves.cancellationdate    AS cancellationdate,
1754                reserves.found               AS found,
1755                reserves.reservenotes        AS reservenotes,
1756                reserves.priority            AS priority,
1757                reserves.timestamp           AS timestamp,
1758                biblioitems.biblioitemnumber AS biblioitemnumber,
1759                reserves.itemnumber          AS itemnumber,
1760                reserves.reserve_id          AS reserve_id,
1761                reserves.itemtype            AS itemtype,
1762                reserves.non_priority        AS non_priority
1763         FROM reserves
1764         JOIN biblioitems USING (biblionumber)
1765         JOIN hold_fill_targets USING (reserve_id)
1766         WHERE found IS NULL
1767         AND priority > 0
1768         AND item_level_request = 0
1769         AND hold_fill_targets.itemnumber = ?
1770         AND reservedate <= DATE_ADD(NOW(),INTERVAL ? DAY)
1771         AND suspend = 0
1772         ORDER BY priority
1773     };
1774     $sth = $dbh->prepare($title_level_target_query);
1775     $sth->execute($itemnumber, $lookahead||0);
1776     @results = ();
1777     if ( my $data = $sth->fetchrow_hashref ) {
1778         push( @results, $data )
1779           unless any{ $data->{borrowernumber} eq $_ } @$ignore_borrowers ;
1780     }
1781     return @results if @results;
1782
1783     my $query = qq{
1784         SELECT reserves.biblionumber               AS biblionumber,
1785                reserves.borrowernumber             AS borrowernumber,
1786                reserves.reservedate                AS reservedate,
1787                reserves.waitingdate                AS waitingdate,
1788                reserves.branchcode                 AS branchcode,
1789                reserves.cancellationdate           AS cancellationdate,
1790                reserves.found                      AS found,
1791                reserves.reservenotes               AS reservenotes,
1792                reserves.priority                   AS priority,
1793                reserves.timestamp                  AS timestamp,
1794                reserves.itemnumber                 AS itemnumber,
1795                reserves.reserve_id                 AS reserve_id,
1796                reserves.itemtype                   AS itemtype,
1797                reserves.non_priority        AS non_priority
1798         FROM reserves
1799         WHERE reserves.biblionumber = ?
1800           AND (reserves.itemnumber IS NULL OR reserves.itemnumber = ?)
1801           AND reserves.reservedate <= DATE_ADD(NOW(),INTERVAL ? DAY)
1802           AND suspend = 0
1803           ORDER BY priority
1804     };
1805     $sth = $dbh->prepare($query);
1806     $sth->execute( $biblio, $itemnumber, $lookahead||0);
1807     @results = ();
1808     while ( my $data = $sth->fetchrow_hashref ) {
1809         push( @results, $data )
1810           unless any{ $data->{borrowernumber} eq $_ } @$ignore_borrowers ;
1811     }
1812     return @results;
1813 }
1814
1815 =head2 _koha_notify_reserve
1816
1817   _koha_notify_reserve( $hold->reserve_id );
1818
1819 Sends a notification to the patron that their hold has been filled (through
1820 ModReserveAffect, _not_ ModReserveFill)
1821
1822 The letter code for this notice may be found using the following query:
1823
1824     select distinct letter_code
1825     from message_transports
1826     inner join message_attributes using (message_attribute_id)
1827     where message_name = 'Hold_Filled'
1828
1829 This will probably sipmly be 'HOLD', but because it is defined in the database,
1830 it is subject to addition or change.
1831
1832 The following tables are availalbe witin the notice:
1833
1834     branches
1835     borrowers
1836     biblio
1837     biblioitems
1838     reserves
1839     items
1840
1841 =cut
1842
1843 sub _koha_notify_reserve {
1844     my $reserve_id = shift;
1845     my $hold = Koha::Holds->find($reserve_id);
1846     my $borrowernumber = $hold->borrowernumber;
1847
1848     my $patron = Koha::Patrons->find( $borrowernumber );
1849
1850     # Try to get the borrower's email address
1851     my $to_address = $patron->notice_email_address;
1852
1853     my $messagingprefs = C4::Members::Messaging::GetMessagingPreferences( {
1854             borrowernumber => $borrowernumber,
1855             message_name => 'Hold_Filled'
1856     } );
1857
1858     my $library = Koha::Libraries->find( $hold->branchcode );
1859     my $admin_email_address = $library->from_email_address;
1860     $library = $library->unblessed;
1861
1862     my %letter_params = (
1863         module => 'reserves',
1864         branchcode => $hold->branchcode,
1865         lang => $patron->lang,
1866         tables => {
1867             'branches'       => $library,
1868             'borrowers'      => $patron->unblessed,
1869             'biblio'         => $hold->biblionumber,
1870             'biblioitems'    => $hold->biblionumber,
1871             'reserves'       => $hold->unblessed,
1872             'items'          => $hold->itemnumber,
1873         },
1874     );
1875
1876     my $notification_sent = 0; #Keeping track if a Hold_filled message is sent. If no message can be sent, then default to a print message.
1877     my $send_notification = sub {
1878         my ( $mtt, $letter_code ) = (@_);
1879         return unless defined $letter_code;
1880         $letter_params{letter_code} = $letter_code;
1881         $letter_params{message_transport_type} = $mtt;
1882         my $letter =  C4::Letters::GetPreparedLetter ( %letter_params );
1883         unless ($letter) {
1884             warn "Could not find a letter called '$letter_params{'letter_code'}' for $mtt in the 'reserves' module";
1885             return;
1886         }
1887
1888         C4::Letters::EnqueueLetter( {
1889             letter => $letter,
1890             borrowernumber => $borrowernumber,
1891             from_address => $admin_email_address,
1892             message_transport_type => $mtt,
1893         } );
1894     };
1895
1896     while ( my ( $mtt, $letter_code ) = each %{ $messagingprefs->{transports} } ) {
1897         next if (
1898                ( $mtt eq 'email' and not $to_address ) # No email address
1899             or ( $mtt eq 'sms'   and not $patron->smsalertnumber ) # No SMS number
1900             or ( $mtt eq 'itiva' and C4::Context->preference('TalkingTechItivaPhoneNotification') ) # Notice is handled by TalkingTech_itiva_outbound.pl
1901             or ( $mtt eq 'phone' and not $patron->phone ) # No phone number to call
1902         );
1903
1904         &$send_notification($mtt, $letter_code);
1905         $notification_sent++;
1906     }
1907     #Making sure that a print notification is sent if no other transport types can be utilized.
1908     if (! $notification_sent) {
1909         &$send_notification('print', 'HOLD');
1910     }
1911
1912 }
1913
1914 =head2 _ShiftPriorityByDateAndPriority
1915
1916   $new_priority = _ShiftPriorityByDateAndPriority( $biblionumber, $reservedate, $priority );
1917
1918 This increments the priority of all reserves after the one
1919 with either the lowest date after C<$reservedate>
1920 or the lowest priority after C<$priority>.
1921
1922 It effectively makes room for a new reserve to be inserted with a certain
1923 priority, which is returned.
1924
1925 This is most useful when the reservedate can be set by the user.  It allows
1926 the new reserve to be placed before other reserves that have a later
1927 reservedate.  Since priority also is set by the form in reserves/request.pl
1928 the sub accounts for that too.
1929
1930 =cut
1931
1932 sub _ShiftPriorityByDateAndPriority {
1933     my ( $biblio, $resdate, $new_priority ) = @_;
1934
1935     my $dbh = C4::Context->dbh;
1936     my $query = "SELECT priority FROM reserves WHERE biblionumber = ? AND ( reservedate > ? OR priority > ? ) ORDER BY priority ASC LIMIT 1";
1937     my $sth = $dbh->prepare( $query );
1938     $sth->execute( $biblio, $resdate, $new_priority );
1939     my $min_priority = $sth->fetchrow;
1940     # if no such matches are found, $new_priority remains as original value
1941     $new_priority = $min_priority if ( $min_priority );
1942
1943     # Shift the priority up by one; works in conjunction with the next SQL statement
1944     $query = "UPDATE reserves
1945               SET priority = priority+1
1946               WHERE biblionumber = ?
1947               AND borrowernumber = ?
1948               AND reservedate = ?
1949               AND found IS NULL";
1950     my $sth_update = $dbh->prepare( $query );
1951
1952     # Select all reserves for the biblio with priority greater than $new_priority, and order greatest to least
1953     $query = "SELECT borrowernumber, reservedate FROM reserves WHERE priority >= ? AND biblionumber = ? ORDER BY priority DESC";
1954     $sth = $dbh->prepare( $query );
1955     $sth->execute( $new_priority, $biblio );
1956     while ( my $row = $sth->fetchrow_hashref ) {
1957         $sth_update->execute( $biblio, $row->{borrowernumber}, $row->{reservedate} );
1958     }
1959
1960     return $new_priority;  # so the caller knows what priority they wind up receiving
1961 }
1962
1963 =head2 MoveReserve
1964
1965   MoveReserve( $itemnumber, $borrowernumber, $cancelreserve )
1966
1967 Use when checking out an item to handle reserves
1968 If $cancelreserve boolean is set to true, it will remove existing reserve
1969
1970 =cut
1971
1972 sub MoveReserve {
1973     my ( $itemnumber, $borrowernumber, $cancelreserve ) = @_;
1974
1975     $cancelreserve //= 0;
1976
1977     my $lookahead = C4::Context->preference('ConfirmFutureHolds'); #number of days to look for future holds
1978     my ( $restype, $res, undef ) = CheckReserves( $itemnumber, undef, $lookahead );
1979     return unless $res;
1980
1981     my $biblionumber     =  $res->{biblionumber};
1982
1983     if ($res->{borrowernumber} == $borrowernumber) {
1984         ModReserveFill($res);
1985     }
1986     else {
1987         # warn "Reserved";
1988         # The item is reserved by someone else.
1989         # Find this item in the reserves
1990
1991         my $borr_res  = Koha::Holds->search({
1992             borrowernumber => $borrowernumber,
1993             biblionumber   => $biblionumber,
1994         },{
1995             order_by       => 'priority'
1996         })->next();
1997
1998         if ( $borr_res ) {
1999             # The item is reserved by the current patron
2000             ModReserveFill($borr_res->unblessed);
2001         }
2002
2003         if ( $cancelreserve eq 'revert' ) { ## Revert waiting reserve to priority 1
2004             RevertWaitingStatus({ itemnumber => $itemnumber });
2005         }
2006         elsif ( $cancelreserve eq 'cancel' || $cancelreserve ) { # cancel reserves on this item
2007             my $hold = Koha::Holds->find( $res->{reserve_id} );
2008             $hold->cancel;
2009         }
2010     }
2011 }
2012
2013 =head2 MergeHolds
2014
2015   MergeHolds($dbh,$to_biblio, $from_biblio);
2016
2017 This shifts the holds from C<$from_biblio> to C<$to_biblio> and reorders them by the date they were placed
2018
2019 =cut
2020
2021 sub MergeHolds {
2022     my ( $dbh, $to_biblio, $from_biblio ) = @_;
2023     my $sth = $dbh->prepare(
2024         "SELECT count(*) as reserve_count FROM reserves WHERE biblionumber = ?"
2025     );
2026     $sth->execute($from_biblio);
2027     if ( my $data = $sth->fetchrow_hashref() ) {
2028
2029         # holds exist on old record, if not we don't need to do anything
2030         $sth = $dbh->prepare(
2031             "UPDATE reserves SET biblionumber = ? WHERE biblionumber = ?");
2032         $sth->execute( $to_biblio, $from_biblio );
2033
2034         # Reorder by date
2035         # don't reorder those already waiting
2036
2037         $sth = $dbh->prepare(
2038 "SELECT * FROM reserves WHERE biblionumber = ? AND (found NOT IN ('W', 'T', 'P') OR found is NULL) ORDER BY reservedate ASC"
2039         );
2040         my $upd_sth = $dbh->prepare(
2041 "UPDATE reserves SET priority = ? WHERE biblionumber = ? AND borrowernumber = ?
2042         AND reservedate = ? AND (itemnumber = ? or itemnumber is NULL) "
2043         );
2044         $sth->execute( $to_biblio );
2045         my $priority = 1;
2046         while ( my $reserve = $sth->fetchrow_hashref() ) {
2047             $upd_sth->execute(
2048                 $priority,                    $to_biblio,
2049                 $reserve->{'borrowernumber'}, $reserve->{'reservedate'},
2050                 $reserve->{'itemnumber'}
2051             );
2052             $priority++;
2053         }
2054     }
2055 }
2056
2057 =head2 RevertWaitingStatus
2058
2059   RevertWaitingStatus({ itemnumber => $itemnumber });
2060
2061   Reverts a 'waiting' hold back to a regular hold with a priority of 1.
2062
2063   Caveat: Any waiting hold fixed with RevertWaitingStatus will be an
2064           item level hold, even if it was only a bibliolevel hold to
2065           begin with. This is because we can no longer know if a hold
2066           was item-level or bib-level after a hold has been set to
2067           waiting status.
2068
2069 =cut
2070
2071 sub RevertWaitingStatus {
2072     my ( $params ) = @_;
2073     my $itemnumber = $params->{'itemnumber'};
2074
2075     return unless ( $itemnumber );
2076
2077     my $dbh = C4::Context->dbh;
2078
2079     ## Get the waiting reserve we want to revert
2080     my $hold = Koha::Holds->search(
2081         {
2082             itemnumber => $itemnumber,
2083             found => { not => undef },
2084         }
2085     )->next;
2086
2087     ## Increment the priority of all other non-waiting
2088     ## reserves for this bib record
2089     my $holds = Koha::Holds->search({ biblionumber => $hold->biblionumber, priority => { '>' => 0 } })
2090                            ->update({ priority => \'priority + 1' }, { no_triggers => 1 });
2091
2092     ## Fix up the currently waiting reserve
2093     $hold->set(
2094         {
2095             priority    => 1,
2096             found       => undef,
2097             waitingdate => undef,
2098             itemnumber  => $hold->item_level_hold ? $hold->itemnumber : undef,
2099         }
2100     )->store();
2101
2102     _FixPriority( { biblionumber => $hold->biblionumber } );
2103
2104     return $hold;
2105 }
2106
2107 =head2 ReserveSlip
2108
2109 ReserveSlip(
2110     {
2111         branchcode     => $branchcode,
2112         borrowernumber => $borrowernumber,
2113         biblionumber   => $biblionumber,
2114         [ itemnumber   => $itemnumber, ]
2115         [ barcode      => $barcode, ]
2116     }
2117   )
2118
2119 Returns letter hash ( see C4::Letters::GetPreparedLetter ) or undef
2120
2121 The letter code will be HOLD_SLIP, and the following tables are
2122 available within the slip:
2123
2124     reserves
2125     branches
2126     borrowers
2127     biblio
2128     biblioitems
2129     items
2130
2131 =cut
2132
2133 sub ReserveSlip {
2134     my ($args) = @_;
2135     my $branchcode     = $args->{branchcode};
2136     my $reserve_id = $args->{reserve_id};
2137
2138     my $hold = Koha::Holds->find($reserve_id);
2139     return unless $hold;
2140
2141     my $patron = $hold->borrower;
2142     my $reserve = $hold->unblessed;
2143
2144     return  C4::Letters::GetPreparedLetter (
2145         module => 'circulation',
2146         letter_code => 'HOLD_SLIP',
2147         branchcode => $branchcode,
2148         lang => $patron->lang,
2149         tables => {
2150             'reserves'    => $reserve,
2151             'branches'    => $reserve->{branchcode},
2152             'borrowers'   => $reserve->{borrowernumber},
2153             'biblio'      => $reserve->{biblionumber},
2154             'biblioitems' => $reserve->{biblionumber},
2155             'items'       => $reserve->{itemnumber},
2156         },
2157     );
2158 }
2159
2160 =head2 GetReservesControlBranch
2161
2162   my $reserves_control_branch = GetReservesControlBranch($item, $borrower);
2163
2164   Return the branchcode to be used to determine which reserves
2165   policy applies to a transaction.
2166
2167   C<$item> is a hashref for an item. Only 'homebranch' is used.
2168
2169   C<$borrower> is a hashref to borrower. Only 'branchcode' is used.
2170
2171 =cut
2172
2173 sub GetReservesControlBranch {
2174     my ( $item, $borrower ) = @_;
2175
2176     my $reserves_control = C4::Context->preference('ReservesControlBranch');
2177
2178     my $branchcode =
2179         ( $reserves_control eq 'ItemHomeLibrary' ) ? $item->{'homebranch'}
2180       : ( $reserves_control eq 'PatronLibrary' )   ? $borrower->{'branchcode'}
2181       :                                              undef;
2182
2183     return $branchcode;
2184 }
2185
2186 =head2 CalculatePriority
2187
2188     my $p = CalculatePriority($biblionumber, $resdate);
2189
2190 Calculate priority for a new reserve on biblionumber, placing it at
2191 the end of the line of all holds whose start date falls before
2192 the current system time and that are neither on the hold shelf
2193 or in transit.
2194
2195 The reserve date parameter is optional; if it is supplied, the
2196 priority is based on the set of holds whose start date falls before
2197 the parameter value.
2198
2199 After calculation of this priority, it is recommended to call
2200 _ShiftPriorityByDateAndPriority. Note that this is currently done in
2201 AddReserves.
2202
2203 =cut
2204
2205 sub CalculatePriority {
2206     my ( $biblionumber, $resdate ) = @_;
2207
2208     my $sql = q{
2209         SELECT COUNT(*) FROM reserves
2210         WHERE biblionumber = ?
2211         AND   priority > 0
2212         AND   (found IS NULL OR found = '')
2213     };
2214     #skip found==W or found==T or found==P (waiting, transit or processing holds)
2215     if( $resdate ) {
2216         $sql.= ' AND ( reservedate <= ? )';
2217     }
2218     else {
2219         $sql.= ' AND ( reservedate < NOW() )';
2220     }
2221     my $dbh = C4::Context->dbh();
2222     my @row = $dbh->selectrow_array(
2223         $sql,
2224         undef,
2225         $resdate ? ($biblionumber, $resdate) : ($biblionumber)
2226     );
2227
2228     return @row ? $row[0]+1 : 1;
2229 }
2230
2231 =head2 IsItemOnHoldAndFound
2232
2233     my $bool = IsItemFoundHold( $itemnumber );
2234
2235     Returns true if the item is currently on hold
2236     and that hold has a non-null found status ( W, T, etc. )
2237
2238 =cut
2239
2240 sub IsItemOnHoldAndFound {
2241     my ($itemnumber) = @_;
2242
2243     my $rs = Koha::Database->new()->schema()->resultset('Reserve');
2244
2245     my $found = $rs->count(
2246         {
2247             itemnumber => $itemnumber,
2248             found      => { '!=' => undef }
2249         }
2250     );
2251
2252     return $found;
2253 }
2254
2255 =head2 GetMaxPatronHoldsForRecord
2256
2257 my $holds_per_record = ReservesControlBranch( $borrowernumber, $biblionumber );
2258
2259 For multiple holds on a given record for a given patron, the max
2260 number of record level holds that a patron can be placed is the highest
2261 value of the holds_per_record rule for each item if the record for that
2262 patron. This subroutine finds and returns the highest holds_per_record
2263 rule value for a given patron id and record id.
2264
2265 =cut
2266
2267 sub GetMaxPatronHoldsForRecord {
2268     my ( $borrowernumber, $biblionumber ) = @_;
2269
2270     my $patron = Koha::Patrons->find($borrowernumber);
2271     my @items = Koha::Items->search( { biblionumber => $biblionumber } );
2272
2273     my $controlbranch = C4::Context->preference('ReservesControlBranch');
2274
2275     my $categorycode = $patron->categorycode;
2276     my $branchcode;
2277     $branchcode = $patron->branchcode if ( $controlbranch eq "PatronLibrary" );
2278
2279     my $max = 0;
2280     foreach my $item (@items) {
2281         my $itemtype = $item->effective_itemtype();
2282
2283         $branchcode = $item->homebranch if ( $controlbranch eq "ItemHomeLibrary" );
2284
2285         my $rule = Koha::CirculationRules->get_effective_rule({
2286             categorycode => $categorycode,
2287             itemtype     => $itemtype,
2288             branchcode   => $branchcode,
2289             rule_name    => 'holds_per_record'
2290         });
2291         my $holds_per_record = $rule ? $rule->rule_value : 0;
2292         $max = $holds_per_record if $holds_per_record > $max;
2293     }
2294
2295     return $max;
2296 }
2297
2298 =head1 AUTHOR
2299
2300 Koha Development Team <http://koha-community.org/>
2301
2302 =cut
2303
2304 1;