Koha/REST/V1/Holds.pm

   1 package Koha::REST::V1::Holds;
   2
   3 # This file is part of Koha.
   4 #
   5 # Koha is free software; you can redistribute it and/or modify it
   6 # under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation; either version 3 of the License, or
   8 # (at your option) any later version.
   9 #
  10 # Koha is distributed in the hope that it will be useful, but
  11 # WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with Koha; if not, see <http://www.gnu.org/licenses>.
  17
  18 use Modern::Perl;
  19
  20 use Mojo::Base 'Mojolicious::Controller';
  21
  22 use Mojo::JSON;
  23
  24 use C4::Reserves;
  25
  26 use Koha::Items;
  27 use Koha::Patrons;
  28 use Koha::Holds;
  29 use Koha::DateUtils qw( dt_from_string );
  30
  31 use List::MoreUtils qw( any );
  32 use Try::Tiny qw( catch try );
  33
  34 =head1 API
  35
  36 =head2 Methods
  37
  38 =head3 list
  39
  40 Method that handles listing Koha::Hold objects
  41
  42 =cut
  43
  44 sub list {
  45     my $c = shift->openapi->valid_input or return;
  46
  47     return try {
  48         my $holds_set = Koha::Holds->new;
  49         my $holds     = $c->objects->search( $holds_set );
  50         return $c->render( status => 200, openapi => $holds );
  51     }
  52     catch {
  53         $c->unhandled_exception($_);
  54     };
  55 }
  56
  57 =head3 add
  58
  59 Method that handles adding a new Koha::Hold object
  60
  61 =cut
  62
  63 sub add {
  64     my $c = shift->openapi->valid_input or return;
  65
  66     return try {
  67         my $body = $c->validation->param('body');
  68
  69         my $biblio;
  70         my $item;
  71
  72         my $biblio_id         = $body->{biblio_id};
  73         my $item_group_id     = $body->{item_group_id};
  74         my $pickup_library_id = $body->{pickup_library_id};
  75         my $item_id           = $body->{item_id};
  76         my $patron_id         = $body->{patron_id};
  77         my $item_type         = $body->{item_type};
  78         my $expiration_date   = $body->{expiration_date};
  79         my $notes             = $body->{notes};
  80         my $hold_date         = $body->{hold_date};
  81         my $non_priority      = $body->{non_priority};
  82
  83         my $overrides = $c->stash('koha.overrides');
  84         my $can_override = $overrides->{any} && C4::Context->preference('AllowHoldPolicyOverride');
  85
  86         if(!C4::Context->preference( 'AllowHoldDateInFuture' ) && $hold_date) {
  87             return $c->render(
  88                 status  => 400,
  89                 openapi => { error => "Hold date in future not allowed" }
  90             );
  91         }
  92
  93         if ( $item_id and $biblio_id ) {
  94
  95             # check they are consistent
  96             unless ( Koha::Items->search( { itemnumber => $item_id, biblionumber => $biblio_id } )
  97                 ->count > 0 )
  98             {
  99                 return $c->render(
 100                     status  => 400,
 101                     openapi => { error => "Item $item_id doesn't belong to biblio $biblio_id" }
 102                 );
 103             }
 104             else {
 105                 $biblio = Koha::Biblios->find($biblio_id);
 106             }
 107         }
 108         elsif ($item_id) {
 109             $item = Koha::Items->find($item_id);
 110
 111             unless ($item) {
 112                 return $c->render(
 113                     status  => 404,
 114                     openapi => { error => "item_id not found." }
 115                 );
 116             }
 117             else {
 118                 $biblio = $item->biblio;
 119             }
 120         }
 121         elsif ($biblio_id) {
 122             $biblio = Koha::Biblios->find($biblio_id);
 123         }
 124         else {
 125             return $c->render(
 126                 status  => 400,
 127                 openapi => { error => "At least one of biblio_id, item_id should be given" }
 128             );
 129         }
 130
 131         unless ($biblio) {
 132             return $c->render(
 133                 status  => 400,
 134                 openapi => "Biblio not found."
 135             );
 136         }
 137
 138         my $patron = Koha::Patrons->find( $patron_id );
 139         unless ($patron) {
 140             return $c->render(
 141                 status  => 400,
 142                 openapi => { error => 'patron_id not found' }
 143             );
 144         }
 145
 146         # If the hold is being forced, no need to validate
 147         unless( $can_override ){
 148             # Validate pickup location
 149             my $valid_pickup_location;
 150             if ($item) {    # item-level hold
 151                 $valid_pickup_location =
 152                   any { $_->branchcode eq $pickup_library_id }
 153                 $item->pickup_locations(
 154                     { patron => $patron } )->as_list;
 155             }
 156             else {
 157                 $valid_pickup_location =
 158                   any { $_->branchcode eq $pickup_library_id }
 159                 $biblio->pickup_locations(
 160                     { patron => $patron } )->as_list;
 161             }
 162
 163             return $c->render(
 164                 status  => 400,
 165                 openapi => {
 166                     error => 'The supplied pickup location is not valid'
 167                 }
 168             ) unless $valid_pickup_location;
 169
 170             my $can_place_hold
 171                 = $item
 172                 ? C4::Reserves::CanItemBeReserved( $patron, $item )
 173                 : C4::Reserves::CanBookBeReserved( $patron_id, $biblio_id );
 174
 175             if ( C4::Context->preference('maxreserves') && $patron->holds->count + 1 > C4::Context->preference('maxreserves') ) {
 176                 $can_place_hold->{status} = 'tooManyReserves';
 177             }
 178
 179             unless ( $can_place_hold->{status} eq 'OK' ) {
 180                 return $c->render(
 181                     status => 403,
 182                     openapi =>
 183                         { error => "Hold cannot be placed. Reason: " . $can_place_hold->{status} }
 184                 );
 185             }
 186         }
 187
 188         my $priority = C4::Reserves::CalculatePriority($biblio_id);
 189
 190         my $hold_id = C4::Reserves::AddReserve(
 191             {
 192                 branchcode       => $pickup_library_id,
 193                 borrowernumber   => $patron_id,
 194                 biblionumber     => $biblio->id,
 195                 priority         => $priority,
 196                 reservation_date => $hold_date,
 197                 expiration_date  => $expiration_date,
 198                 notes            => $notes,
 199                 title            => $biblio->title,
 200                 itemnumber       => $item_id,
 201                 found            => undef,                # TODO: Why not?
 202                 itemtype         => $item_type,
 203                 non_priority     => $non_priority,
 204                 item_group_id    => $item_group_id,
 205             }
 206         );
 207
 208         unless ($hold_id) {
 209             return $c->render(
 210                 status  => 500,
 211                 openapi => 'Error placing the hold. See Koha logs for details.'
 212             );
 213         }
 214
 215         my $hold = Koha::Holds->find($hold_id);
 216
 217         return $c->render(
 218             status  => 201,
 219             openapi => $hold->to_api
 220         );
 221     }
 222     catch {
 223         if ( blessed $_ and $_->isa('Koha::Exceptions') ) {
 224             if ( $_->isa('Koha::Exceptions::Object::FKConstraint') ) {
 225                 my $broken_fk = $_->broken_fk;
 226
 227                 if ( grep { $_ eq $broken_fk } keys %{Koha::Holds->new->to_api_mapping} ) {
 228                     $c->render(
 229                         status  => 404,
 230                         openapi => Koha::Holds->new->to_api_mapping->{$broken_fk} . ' not found.'
 231                     );
 232                 }
 233             }
 234         }
 235
 236         $c->unhandled_exception($_);
 237     };
 238 }
 239
 240 =head3 edit
 241
 242 Method that handles modifying a Koha::Hold object
 243
 244 =cut
 245
 246 sub edit {
 247     my $c = shift->openapi->valid_input or return;
 248
 249     return try {
 250         my $hold_id = $c->validation->param('hold_id');
 251         my $hold = Koha::Holds->find( $hold_id );
 252
 253         unless ($hold) {
 254             return $c->render(
 255                 status  => 404,
 256                 openapi => { error => "Hold not found" }
 257             );
 258         }
 259
 260         my $overrides = $c->stash('koha.overrides');
 261         my $can_override = $overrides->{any} && C4::Context->preference('AllowHoldPolicyOverride');
 262
 263         my $body = $c->validation->output->{body};
 264
 265         my $pickup_library_id = $body->{pickup_library_id};
 266
 267         if (
 268             defined $pickup_library_id
 269             && ( !$hold->is_pickup_location_valid({ library_id => $pickup_library_id }) && !$can_override )
 270           )
 271         {
 272             return $c->render(
 273                 status  => 400,
 274                 openapi => {
 275                     error => 'The supplied pickup location is not valid'
 276                 }
 277             );
 278         }
 279
 280         $pickup_library_id //= $hold->branchcode;
 281         my $priority         = $body->{priority} // $hold->priority;
 282         # suspended_until can also be set to undef
 283         my $suspended_until = $body->{suspended_until} || $hold->suspend_until;
 284
 285         my $params = {
 286             reserve_id    => $hold_id,
 287             branchcode    => $pickup_library_id,
 288             rank          => $priority,
 289             suspend_until => $suspended_until,
 290             itemnumber    => $hold->itemnumber,
 291         };
 292
 293         C4::Reserves::ModReserve($params);
 294         $hold->discard_changes; # refresh
 295
 296         return $c->render(
 297             status  => 200,
 298             openapi => $hold->to_api
 299         );
 300     }
 301     catch {
 302         $c->unhandled_exception($_);
 303     };
 304 }
 305
 306 =head3 delete
 307
 308 Method that handles deleting a Koha::Hold object
 309
 310 =cut
 311
 312 sub delete {
 313     my $c = shift->openapi->valid_input or return;
 314
 315     my $hold_id = $c->validation->param('hold_id');
 316     my $hold    = Koha::Holds->find($hold_id);
 317
 318     unless ($hold) {
 319         return $c->render( status => 404, openapi => { error => "Hold not found." } );
 320     }
 321
 322     return try {
 323         $hold->cancel;
 324
 325         return $c->render(
 326             status  => 204,
 327             openapi => q{}
 328         );
 329     }
 330     catch {
 331         $c->unhandled_exception($_);
 332     };
 333 }
 334
 335 =head3 suspend
 336
 337 Method that handles suspending a hold
 338
 339 =cut
 340
 341 sub suspend {
 342     my $c = shift->openapi->valid_input or return;
 343
 344     my $hold_id  = $c->validation->param('hold_id');
 345     my $hold     = Koha::Holds->find($hold_id);
 346     my $body     = $c->req->json;
 347     my $end_date = ($body) ? $body->{end_date} : undef;
 348
 349     unless ($hold) {
 350         return $c->render( status => 404, openapi => { error => 'Hold not found.' } );
 351     }
 352
 353     return try {
 354         $hold->suspend_hold($end_date);
 355         $hold->discard_changes;
 356         $c->res->headers->location( $c->req->url->to_string );
 357
 358         my $suspend_until = $end_date ? dt_from_string($hold->suspend_until)->ymd : undef;
 359         return $c->render(
 360             status  => 201,
 361             openapi => {
 362                 end_date => $suspend_until,
 363             }
 364         );
 365     }
 366     catch {
 367         if ( blessed $_ and $_->isa('Koha::Exceptions::Hold::CannotSuspendFound') ) {
 368             return $c->render( status => 400, openapi => { error => "$_" } );
 369         }
 370
 371         $c->unhandled_exception($_);
 372     };
 373 }
 374
 375 =head3 resume
 376
 377 Method that handles resuming a hold
 378
 379 =cut
 380
 381 sub resume {
 382     my $c = shift->openapi->valid_input or return;
 383
 384     my $hold_id = $c->validation->param('hold_id');
 385     my $hold    = Koha::Holds->find($hold_id);
 386     my $body    = $c->req->json;
 387
 388     unless ($hold) {
 389         return $c->render( status => 404, openapi => { error => 'Hold not found.' } );
 390     }
 391
 392     return try {
 393         $hold->resume;
 394         return $c->render( status => 204, openapi => {} );
 395     }
 396     catch {
 397         $c->unhandled_exception($_);
 398     };
 399 }
 400
 401 =head3 update_priority
 402
 403 Method that handles modifying a Koha::Hold object
 404
 405 =cut
 406
 407 sub update_priority {
 408     my $c = shift->openapi->valid_input or return;
 409
 410     my $hold_id = $c->validation->param('hold_id');
 411     my $hold = Koha::Holds->find($hold_id);
 412
 413     unless ($hold) {
 414         return $c->render(
 415             status  => 404,
 416             openapi => { error => "Hold not found" }
 417         );
 418     }
 419
 420     return try {
 421         my $priority = $c->req->json;
 422         C4::Reserves::_FixPriority(
 423             {
 424                 reserve_id => $hold_id,
 425                 rank       => $priority
 426             }
 427         );
 428
 429         return $c->render( status => 200, openapi => $priority );
 430     }
 431     catch {
 432         $c->unhandled_exception($_);
 433     };
 434 }
 435
 436 =head3 pickup_locations
 437
 438 Method that returns the possible pickup_locations for a given hold
 439 used for building the dropdown selector
 440
 441 =cut
 442
 443 sub pickup_locations {
 444     my $c = shift->openapi->valid_input or return;
 445
 446     my $hold_id = $c->validation->param('hold_id');
 447     my $hold = Koha::Holds->find( $hold_id, { prefetch => [ 'patron' ] } );
 448
 449     unless ($hold) {
 450         return $c->render(
 451             status  => 404,
 452             openapi => { error => "Hold not found" }
 453         );
 454     }
 455
 456     return try {
 457         my $ps_set;
 458
 459         if ( $hold->itemnumber ) {
 460             $ps_set = $hold->item->pickup_locations( { patron => $hold->patron } );
 461         }
 462         else {
 463             $ps_set = $hold->biblio->pickup_locations( { patron => $hold->patron } );
 464         }
 465
 466         my $pickup_locations = $c->objects->search( $ps_set );
 467         my @response = ();
 468
 469         if ( C4::Context->preference('AllowHoldPolicyOverride') ) {
 470
 471             my $libraries_rs = Koha::Libraries->search( { pickup_location => 1 } );
 472             my $libraries    = $c->objects->search($libraries_rs);
 473
 474             @response = map {
 475                 my $library = $_;
 476                 $library->{needs_override} = (
 477                     any { $_->{library_id} eq $library->{library_id} }
 478                     @{$pickup_locations}
 479                   )
 480                   ? Mojo::JSON->false
 481                   : Mojo::JSON->true;
 482                 $library;
 483             } @{$libraries};
 484
 485             return $c->render(
 486                 status  => 200,
 487                 openapi => \@response
 488             );
 489         }
 490
 491         @response = map { $_->{needs_override} = Mojo::JSON->false; $_; } @{$pickup_locations};
 492
 493         return $c->render(
 494             status  => 200,
 495             openapi => \@response
 496         );
 497     }
 498     catch {
 499         $c->unhandled_exception($_);
 500     };
 501 }
 502
 503 =head3 update_pickup_location
 504
 505 Method that handles modifying the pickup location of a Koha::Hold object
 506
 507 =cut
 508
 509 sub update_pickup_location {
 510     my $c = shift->openapi->valid_input or return;
 511
 512     my $hold_id = $c->validation->param('hold_id');
 513     my $body    = $c->validation->param('body');
 514     my $pickup_library_id = $body->{pickup_library_id};
 515
 516     my $hold = Koha::Holds->find($hold_id);
 517
 518     unless ($hold) {
 519         return $c->render(
 520             status  => 404,
 521             openapi => { error => "Hold not found" }
 522         );
 523     }
 524
 525     return try {
 526
 527         my $overrides    = $c->stash('koha.overrides');
 528         my $can_override = $overrides->{any} && C4::Context->preference('AllowHoldPolicyOverride');
 529
 530         $hold->set_pickup_location(
 531             {
 532                 library_id => $pickup_library_id,
 533                 force      => $can_override
 534             }
 535         );
 536
 537         return $c->render(
 538             status  => 200,
 539             openapi => {
 540                 pickup_library_id => $pickup_library_id
 541             }
 542         );
 543     }
 544     catch {
 545
 546         if ( blessed $_ and $_->isa('Koha::Exceptions::Hold::InvalidPickupLocation') ) {
 547             return $c->render(
 548                 status  => 400,
 549                 openapi => {
 550                     error => "$_"
 551                 }
 552             );
 553         }
 554
 555         $c->unhandled_exception($_);
 556     };
 557 }
 558
 559
 560 1;