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         # Validate pickup location
 147         my $valid_pickup_location;
 148         if ($item) {    # item-level hold
 149             $valid_pickup_location =
 150               any { $_->branchcode eq $pickup_library_id }
 151             $item->pickup_locations(
 152                 { patron => $patron } )->as_list;
 153         }
 154         else {
 155             $valid_pickup_location =
 156               any { $_->branchcode eq $pickup_library_id }
 157             $biblio->pickup_locations(
 158                 { patron => $patron } )->as_list;
 159         }
 160
 161         return $c->render(
 162             status  => 400,
 163             openapi => {
 164                 error => 'The supplied pickup location is not valid'
 165             }
 166         ) unless $valid_pickup_location || $can_override;
 167
 168         my $can_place_hold
 169             = $item
 170             ? C4::Reserves::CanItemBeReserved( $patron, $item )
 171             : C4::Reserves::CanBookBeReserved( $patron_id, $biblio_id );
 172
 173         if ( C4::Context->preference('maxreserves') && $patron->holds->count + 1 > C4::Context->preference('maxreserves') ) {
 174             $can_place_hold->{status} = 'tooManyReserves';
 175         }
 176
 177         unless ( $can_override || $can_place_hold->{status} eq 'OK' ) {
 178             return $c->render(
 179                 status => 403,
 180                 openapi =>
 181                     { error => "Hold cannot be placed. Reason: " . $can_place_hold->{status} }
 182             );
 183         }
 184
 185         my $priority = C4::Reserves::CalculatePriority($biblio_id);
 186
 187         my $hold_id = C4::Reserves::AddReserve(
 188             {
 189                 branchcode       => $pickup_library_id,
 190                 borrowernumber   => $patron_id,
 191                 biblionumber     => $biblio->id,
 192                 priority         => $priority,
 193                 reservation_date => $hold_date,
 194                 expiration_date  => $expiration_date,
 195                 notes            => $notes,
 196                 title            => $biblio->title,
 197                 itemnumber       => $item_id,
 198                 found            => undef,                # TODO: Why not?
 199                 itemtype         => $item_type,
 200                 non_priority     => $non_priority,
 201                 item_group_id    => $item_group_id,
 202             }
 203         );
 204
 205         unless ($hold_id) {
 206             return $c->render(
 207                 status  => 500,
 208                 openapi => 'Error placing the hold. See Koha logs for details.'
 209             );
 210         }
 211
 212         my $hold = Koha::Holds->find($hold_id);
 213
 214         return $c->render(
 215             status  => 201,
 216             openapi => $hold->to_api
 217         );
 218     }
 219     catch {
 220         if ( blessed $_ and $_->isa('Koha::Exceptions') ) {
 221             if ( $_->isa('Koha::Exceptions::Object::FKConstraint') ) {
 222                 my $broken_fk = $_->broken_fk;
 223
 224                 if ( grep { $_ eq $broken_fk } keys %{Koha::Holds->new->to_api_mapping} ) {
 225                     $c->render(
 226                         status  => 404,
 227                         openapi => Koha::Holds->new->to_api_mapping->{$broken_fk} . ' not found.'
 228                     );
 229                 }
 230             }
 231         }
 232
 233         $c->unhandled_exception($_);
 234     };
 235 }
 236
 237 =head3 edit
 238
 239 Method that handles modifying a Koha::Hold object
 240
 241 =cut
 242
 243 sub edit {
 244     my $c = shift->openapi->valid_input or return;
 245
 246     return try {
 247         my $hold_id = $c->validation->param('hold_id');
 248         my $hold = Koha::Holds->find( $hold_id );
 249
 250         unless ($hold) {
 251             return $c->render(
 252                 status  => 404,
 253                 openapi => { error => "Hold not found" }
 254             );
 255         }
 256
 257         my $overrides = $c->stash('koha.overrides');
 258         my $can_override = $overrides->{any} && C4::Context->preference('AllowHoldPolicyOverride');
 259
 260         my $body = $c->validation->output->{body};
 261
 262         my $pickup_library_id = $body->{pickup_library_id};
 263
 264         if (
 265             defined $pickup_library_id
 266             && ( !$hold->is_pickup_location_valid({ library_id => $pickup_library_id }) && !$can_override )
 267           )
 268         {
 269             return $c->render(
 270                 status  => 400,
 271                 openapi => {
 272                     error => 'The supplied pickup location is not valid'
 273                 }
 274             );
 275         }
 276
 277         $pickup_library_id //= $hold->branchcode;
 278         my $priority         = $body->{priority} // $hold->priority;
 279         # suspended_until can also be set to undef
 280         my $suspended_until = $body->{suspended_until} || $hold->suspend_until;
 281
 282         my $params = {
 283             reserve_id    => $hold_id,
 284             branchcode    => $pickup_library_id,
 285             rank          => $priority,
 286             suspend_until => $suspended_until,
 287             itemnumber    => $hold->itemnumber,
 288         };
 289
 290         C4::Reserves::ModReserve($params);
 291         $hold->discard_changes; # refresh
 292
 293         return $c->render(
 294             status  => 200,
 295             openapi => $hold->to_api
 296         );
 297     }
 298     catch {
 299         $c->unhandled_exception($_);
 300     };
 301 }
 302
 303 =head3 delete
 304
 305 Method that handles deleting a Koha::Hold object
 306
 307 =cut
 308
 309 sub delete {
 310     my $c = shift->openapi->valid_input or return;
 311
 312     my $hold_id = $c->validation->param('hold_id');
 313     my $hold    = Koha::Holds->find($hold_id);
 314
 315     unless ($hold) {
 316         return $c->render( status => 404, openapi => { error => "Hold not found." } );
 317     }
 318
 319     return try {
 320         $hold->cancel;
 321
 322         return $c->render(
 323             status  => 204,
 324             openapi => q{}
 325         );
 326     }
 327     catch {
 328         $c->unhandled_exception($_);
 329     };
 330 }
 331
 332 =head3 suspend
 333
 334 Method that handles suspending a hold
 335
 336 =cut
 337
 338 sub suspend {
 339     my $c = shift->openapi->valid_input or return;
 340
 341     my $hold_id  = $c->validation->param('hold_id');
 342     my $hold     = Koha::Holds->find($hold_id);
 343     my $body     = $c->req->json;
 344     my $end_date = ($body) ? $body->{end_date} : undef;
 345
 346     unless ($hold) {
 347         return $c->render( status => 404, openapi => { error => 'Hold not found.' } );
 348     }
 349
 350     return try {
 351         $hold->suspend_hold($end_date);
 352         $hold->discard_changes;
 353         $c->res->headers->location( $c->req->url->to_string );
 354
 355         my $suspend_until = $end_date ? dt_from_string($hold->suspend_until)->ymd : undef;
 356         return $c->render(
 357             status  => 201,
 358             openapi => {
 359                 end_date => $suspend_until,
 360             }
 361         );
 362     }
 363     catch {
 364         if ( blessed $_ and $_->isa('Koha::Exceptions::Hold::CannotSuspendFound') ) {
 365             return $c->render( status => 400, openapi => { error => "$_" } );
 366         }
 367
 368         $c->unhandled_exception($_);
 369     };
 370 }
 371
 372 =head3 resume
 373
 374 Method that handles resuming a hold
 375
 376 =cut
 377
 378 sub resume {
 379     my $c = shift->openapi->valid_input or return;
 380
 381     my $hold_id = $c->validation->param('hold_id');
 382     my $hold    = Koha::Holds->find($hold_id);
 383     my $body    = $c->req->json;
 384
 385     unless ($hold) {
 386         return $c->render( status => 404, openapi => { error => 'Hold not found.' } );
 387     }
 388
 389     return try {
 390         $hold->resume;
 391         return $c->render( status => 204, openapi => {} );
 392     }
 393     catch {
 394         $c->unhandled_exception($_);
 395     };
 396 }
 397
 398 =head3 update_priority
 399
 400 Method that handles modifying a Koha::Hold object
 401
 402 =cut
 403
 404 sub update_priority {
 405     my $c = shift->openapi->valid_input or return;
 406
 407     my $hold_id = $c->validation->param('hold_id');
 408     my $hold = Koha::Holds->find($hold_id);
 409
 410     unless ($hold) {
 411         return $c->render(
 412             status  => 404,
 413             openapi => { error => "Hold not found" }
 414         );
 415     }
 416
 417     return try {
 418         my $priority = $c->req->json;
 419         C4::Reserves::_FixPriority(
 420             {
 421                 reserve_id => $hold_id,
 422                 rank       => $priority
 423             }
 424         );
 425
 426         return $c->render( status => 200, openapi => $priority );
 427     }
 428     catch {
 429         $c->unhandled_exception($_);
 430     };
 431 }
 432
 433 =head3 pickup_locations
 434
 435 Method that returns the possible pickup_locations for a given hold
 436 used for building the dropdown selector
 437
 438 =cut
 439
 440 sub pickup_locations {
 441     my $c = shift->openapi->valid_input or return;
 442
 443     my $hold_id = $c->validation->param('hold_id');
 444     my $hold = Koha::Holds->find( $hold_id, { prefetch => [ 'patron' ] } );
 445
 446     unless ($hold) {
 447         return $c->render(
 448             status  => 404,
 449             openapi => { error => "Hold not found" }
 450         );
 451     }
 452
 453     return try {
 454         my $ps_set;
 455
 456         if ( $hold->itemnumber ) {
 457             $ps_set = $hold->item->pickup_locations( { patron => $hold->patron } );
 458         }
 459         else {
 460             $ps_set = $hold->biblio->pickup_locations( { patron => $hold->patron } );
 461         }
 462
 463         my $pickup_locations = $c->objects->search( $ps_set );
 464         my @response = ();
 465
 466         if ( C4::Context->preference('AllowHoldPolicyOverride') ) {
 467
 468             my $libraries_rs = Koha::Libraries->search( { pickup_location => 1 } );
 469             my $libraries    = $c->objects->search($libraries_rs);
 470
 471             @response = map {
 472                 my $library = $_;
 473                 $library->{needs_override} = (
 474                     any { $_->{library_id} eq $library->{library_id} }
 475                     @{$pickup_locations}
 476                   )
 477                   ? Mojo::JSON->false
 478                   : Mojo::JSON->true;
 479                 $library;
 480             } @{$libraries};
 481
 482             return $c->render(
 483                 status  => 200,
 484                 openapi => \@response
 485             );
 486         }
 487
 488         @response = map { $_->{needs_override} = Mojo::JSON->false; $_; } @{$pickup_locations};
 489
 490         return $c->render(
 491             status  => 200,
 492             openapi => \@response
 493         );
 494     }
 495     catch {
 496         $c->unhandled_exception($_);
 497     };
 498 }
 499
 500 =head3 update_pickup_location
 501
 502 Method that handles modifying the pickup location of a Koha::Hold object
 503
 504 =cut
 505
 506 sub update_pickup_location {
 507     my $c = shift->openapi->valid_input or return;
 508
 509     my $hold_id = $c->validation->param('hold_id');
 510     my $body    = $c->validation->param('body');
 511     my $pickup_library_id = $body->{pickup_library_id};
 512
 513     my $hold = Koha::Holds->find($hold_id);
 514
 515     unless ($hold) {
 516         return $c->render(
 517             status  => 404,
 518             openapi => { error => "Hold not found" }
 519         );
 520     }
 521
 522     return try {
 523
 524         my $overrides    = $c->stash('koha.overrides');
 525         my $can_override = $overrides->{any} && C4::Context->preference('AllowHoldPolicyOverride');
 526
 527         $hold->set_pickup_location(
 528             {
 529                 library_id => $pickup_library_id,
 530                 force      => $can_override
 531             }
 532         );
 533
 534         return $c->render(
 535             status  => 200,
 536             openapi => {
 537                 pickup_library_id => $pickup_library_id
 538             }
 539         );
 540     }
 541     catch {
 542
 543         if ( blessed $_ and $_->isa('Koha::Exceptions::Hold::InvalidPickupLocation') ) {
 544             return $c->render(
 545                 status  => 400,
 546                 openapi => {
 547                     error => "$_"
 548                 }
 549             );
 550         }
 551
 552         $c->unhandled_exception($_);
 553     };
 554 }
 555
 556
 557 1;