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