Open-ILS/src/perlmods/lib/OpenILS/Application/Circ/Holds.pm

   1 # ---------------------------------------------------------------
   2 # Copyright (C) 2005  Georgia Public Library Service
   3 # Bill Erickson <highfalutin@gmail.com>
   4
   5 # This program is free software; you can redistribute it and/or
   6 # modify it under the terms of the GNU General Public License
   7 # as published by the Free Software Foundation; either version 2
   8 # of the License, or (at your option) any later version.
   9
  10 # This program is distributed in the hope that it will be useful,
  11 # but 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
  16
  17 package OpenILS::Application::Circ::Holds;
  18 use base qw/OpenILS::Application/;
  19 use strict; use warnings;
  20 use OpenILS::Application::AppUtils;
  21 use DateTime;
  22 use Data::Dumper;
  23 use OpenSRF::EX qw(:try);
  24 use OpenILS::Perm;
  25 use OpenILS::Event;
  26 use OpenSRF::Utils;
  27 use OpenSRF::Utils::Logger qw(:logger);
  28 use OpenILS::Utils::CStoreEditor q/:funcs/;
  29 use OpenILS::Utils::PermitHold;
  30 use OpenSRF::Utils::SettingsClient;
  31 use OpenILS::Const qw/:const/;
  32 use OpenILS::Application::Circ::Transit;
  33 use OpenILS::Application::Actor::Friends;
  34 use DateTime;
  35 use DateTime::Format::ISO8601;
  36 use OpenSRF::Utils qw/:datetime/;
  37 use Digest::MD5 qw(md5_hex);
  38 use OpenSRF::Utils::Cache;
  39 use OpenSRF::Utils::JSON;
  40 my $apputils = "OpenILS::Application::AppUtils";
  41 my $U = $apputils;
  42
  43 __PACKAGE__->register_method(
  44     method    => "test_and_create_hold_batch",
  45     api_name  => "open-ils.circ.holds.test_and_create.batch",
  46     stream => 1,
  47     signature => {
  48         desc => q/This is for batch creating a set of holds where every field is identical except for the targets./,
  49         params => [
  50             { desc => 'Authentication token', type => 'string' },
  51             { desc => 'Hash of named parameters.  Same as for open-ils.circ.title_hold.is_possible, though the pertinent target field is automatically populated based on the hold_type and the specified list of targets.', type => 'object'},
  52             { desc => 'Array of target ids', type => 'array' }
  53         ],
  54         return => {
  55             desc => 'Array of hold ID on success, -1 on missing arg, event (or ref to array of events) on error(s)',
  56         },
  57     }
  58 );
  59
  60 __PACKAGE__->register_method(
  61     method    => "test_and_create_hold_batch",
  62     api_name  => "open-ils.circ.holds.test_and_create.batch.override",
  63     stream => 1,
  64     signature => {
  65         desc  => '@see open-ils.circ.holds.test_and_create.batch',
  66     }
  67 );
  68
  69
  70 sub test_and_create_hold_batch {
  71     my( $self, $conn, $auth, $params, $target_list, $oargs ) = @_;
  72
  73     my $override = 0;
  74     if ($self->api_name =~ /override/) {
  75         $override = 1;
  76         $oargs = { all => 1 } unless defined $oargs;
  77         $$params{oargs} = $oargs; # for is_possible checking.
  78     }
  79
  80     my $e = new_editor(authtoken=>$auth);
  81     return $e->die_event unless $e->checkauth;
  82     $$params{'requestor'} = $e->requestor->id;
  83
  84     my $target_field;
  85     if ($$params{'hold_type'} eq 'T') { $target_field = 'titleid'; }
  86     elsif ($$params{'hold_type'} eq 'C') { $target_field = 'copy_id'; }
  87     elsif ($$params{'hold_type'} eq 'R') { $target_field = 'copy_id'; }
  88     elsif ($$params{'hold_type'} eq 'F') { $target_field = 'copy_id'; }
  89     elsif ($$params{'hold_type'} eq 'I') { $target_field = 'issuanceid'; }
  90     elsif ($$params{'hold_type'} eq 'V') { $target_field = 'volume_id'; }
  91     elsif ($$params{'hold_type'} eq 'M') { $target_field = 'mrid'; }
  92     elsif ($$params{'hold_type'} eq 'P') { $target_field = 'partid'; }
  93     else { return undef; }
  94
  95     my $formats_map = delete $$params{holdable_formats_map};
  96
  97     foreach (@$target_list) {
  98         $$params{$target_field} = $_;
  99
 100         # copy the requested formats from the target->formats map
 101         # into the top-level formats attr for each hold
 102         $$params{holdable_formats} = $formats_map->{$_};
 103
 104         my $res;
 105         ($res) = $self->method_lookup(
 106             'open-ils.circ.title_hold.is_possible')->run($auth, $params, $override ? $oargs : {});
 107         if ($res->{'success'} == 1) {
 108
 109             $params->{'depth'} = $res->{'depth'} if $res->{'depth'};
 110
 111             # Remove oargs from params so holds can be created.
 112             if ($$params{oargs}) {
 113                 delete $$params{oargs};
 114             }
 115
 116             my $ahr = construct_hold_request_object($params);
 117             my ($res2) = $self->method_lookup(
 118                 $override
 119                 ? 'open-ils.circ.holds.create.override'
 120                 : 'open-ils.circ.holds.create'
 121             )->run($auth, $ahr, $oargs);
 122             $res2 = {
 123                 'target' => $$params{$target_field},
 124                 'result' => $res2
 125             };
 126             $conn->respond($res2);
 127         } else {
 128             $res = {
 129                 'target' => $$params{$target_field},
 130                 'result' => $res
 131             };
 132             $conn->respond($res);
 133         }
 134     }
 135     return undef;
 136 }
 137
 138 sub construct_hold_request_object {
 139     my ($params) = @_;
 140
 141     my $ahr = Fieldmapper::action::hold_request->new;
 142     $ahr->isnew('1');
 143
 144     foreach my $field (keys %{ $params }) {
 145         if ($field eq 'depth') { $ahr->selection_depth($$params{$field}); }
 146         elsif ($field eq 'patronid') {
 147             $ahr->usr($$params{$field}); }
 148         elsif ($field eq 'titleid') { $ahr->target($$params{$field}); }
 149         elsif ($field eq 'copy_id') { $ahr->target($$params{$field}); }
 150         elsif ($field eq 'issuanceid') { $ahr->target($$params{$field}); }
 151         elsif ($field eq 'volume_id') { $ahr->target($$params{$field}); }
 152         elsif ($field eq 'mrid') { $ahr->target($$params{$field}); }
 153         elsif ($field eq 'partid') { $ahr->target($$params{$field}); }
 154         else {
 155             $ahr->$field($$params{$field});
 156         }
 157     }
 158     return $ahr;
 159 }
 160
 161 __PACKAGE__->register_method(
 162     method    => "create_hold_batch",
 163     api_name  => "open-ils.circ.holds.create.batch",
 164     stream => 1,
 165     signature => {
 166         desc => q/@see open-ils.circ.holds.create.batch/,
 167         params => [
 168             { desc => 'Authentication token', type => 'string' },
 169             { desc => 'Array of hold objects', type => 'array' }
 170         ],
 171         return => {
 172             desc => 'Array of hold ID on success, -1 on missing arg, event (or ref to array of events) on error(s)',
 173         },
 174     }
 175 );
 176
 177 __PACKAGE__->register_method(
 178     method    => "create_hold_batch",
 179     api_name  => "open-ils.circ.holds.create.override.batch",
 180     stream => 1,
 181     signature => {
 182         desc  => '@see open-ils.circ.holds.create.batch',
 183     }
 184 );
 185
 186
 187 sub create_hold_batch {
 188     my( $self, $conn, $auth, $hold_list, $oargs ) = @_;
 189     (my $method = $self->api_name) =~ s/\.batch//og;
 190     foreach (@$hold_list) {
 191         my ($res) = $self->method_lookup($method)->run($auth, $_, $oargs);
 192         $conn->respond($res);
 193     }
 194     return undef;
 195 }
 196
 197
 198 __PACKAGE__->register_method(
 199     method    => "create_hold",
 200     api_name  => "open-ils.circ.holds.create",
 201     signature => {
 202         desc => "Create a new hold for an item.  From a permissions perspective, " .
 203                 "the login session is used as the 'requestor' of the hold.  "      .
 204                 "The hold recipient is determined by the 'usr' setting within the hold object. " .
 205                 'First we verify the requestor has holds request permissions.  '         .
 206                 'Then we verify that the recipient is allowed to make the given hold.  ' .
 207                 'If not, we see if the requestor has "override" capabilities.  If not, ' .
 208                 'a permission exception is returned.  If permissions allow, we cycle '   .
 209                 'through the set of holds objects and create.  '                         .
 210                 'If the recipient does not have permission to place multiple holds '     .
 211                 'on a single title and said operation is attempted, a permission '       .
 212                 'exception is returned',
 213         params => [
 214             { desc => 'Authentication token',               type => 'string' },
 215             { desc => 'Hold object for hold to be created',
 216                 type => 'object', class => 'ahr' }
 217         ],
 218         return => {
 219             desc => 'New ahr ID on success, -1 on missing arg, event (or ref to array of events) on error(s)',
 220         },
 221     }
 222 );
 223
 224 __PACKAGE__->register_method(
 225     method    => "create_hold",
 226     api_name  => "open-ils.circ.holds.create.override",
 227     notes     => '@see open-ils.circ.holds.create',
 228     signature => {
 229         desc  => "If the recipient is not allowed to receive the requested hold, " .
 230                  "call this method to attempt the override",
 231         params => [
 232             { desc => 'Authentication token',               type => 'string' },
 233             {
 234                 desc => 'Hold object for hold to be created',
 235                 type => 'object', class => 'ahr'
 236             }
 237         ],
 238         return => {
 239             desc => 'New hold (ahr) ID on success, -1 on missing arg, event (or ref to array of events) on error(s)',
 240         },
 241     }
 242 );
 243
 244 sub create_hold {
 245     my( $self, $conn, $auth, $hold, $oargs ) = @_;
 246     return -1 unless $hold;
 247     my $e = new_editor(authtoken=>$auth, xact=>1);
 248     return $e->die_event unless $e->checkauth;
 249
 250     my $override = 0;
 251     if ($self->api_name =~ /override/) {
 252         $override = 1;
 253         $oargs = { all => 1 } unless defined $oargs;
 254     }
 255
 256     my @events;
 257
 258     my $requestor = $e->requestor;
 259     my $recipient = $requestor;
 260
 261     if( $requestor->id ne $hold->usr ) {
 262         # Make sure the requestor is allowed to place holds for
 263         # the recipient if they are not the same people
 264         $recipient = $e->retrieve_actor_user($hold->usr)  or return $e->die_event;
 265         $e->allowed('REQUEST_HOLDS', $recipient->home_ou) or return $e->die_event;
 266     }
 267
 268     # If the related org setting tells us to, block if patron privs have expired
 269     my $expire_setting = $U->ou_ancestor_setting_value($recipient->home_ou, OILS_SETTING_BLOCK_HOLD_FOR_EXPIRED_PATRON);
 270     if ($expire_setting) {
 271         my $expire = DateTime::Format::ISO8601->new->parse_datetime(
 272             cleanse_ISO8601($recipient->expire_date));
 273
 274         push( @events, OpenILS::Event->new(
 275             'PATRON_ACCOUNT_EXPIRED',
 276             "payload" => {"fail_part" => "actor.usr.privs_expired"}
 277             )) if( CORE::time > $expire->epoch ) ;
 278     }
 279
 280     # Now make sure the recipient is allowed to receive the specified hold
 281     my $porg = $recipient->home_ou;
 282     my $rid  = $e->requestor->id;
 283     my $t    = $hold->hold_type;
 284
 285     # See if a duplicate hold already exists
 286     my $sargs = {
 287         usr              => $recipient->id,
 288         hold_type        => $t,
 289         fulfillment_time => undef,
 290         target           => $hold->target,
 291         cancel_time      => undef,
 292     };
 293
 294     $sargs->{holdable_formats} = $hold->holdable_formats if $t eq 'M';
 295
 296     my $existing = $e->search_action_hold_request($sargs);
 297     push( @events, OpenILS::Event->new('HOLD_EXISTS')) if @$existing;
 298
 299     my $checked_out = hold_item_is_checked_out($e, $recipient->id, $hold->hold_type, $hold->target);
 300     push( @events, OpenILS::Event->new('HOLD_ITEM_CHECKED_OUT')) if $checked_out;
 301
 302     if ( $t eq OILS_HOLD_TYPE_METARECORD ) {
 303         return $e->die_event unless $e->allowed('MR_HOLDS',     $porg);
 304     } elsif ( $t eq OILS_HOLD_TYPE_TITLE ) {
 305         return $e->die_event unless $e->allowed('TITLE_HOLDS',  $porg);
 306     } elsif ( $t eq OILS_HOLD_TYPE_VOLUME ) {
 307         return $e->die_event unless $e->allowed('VOLUME_HOLDS', $porg);
 308     } elsif ( $t eq OILS_HOLD_TYPE_MONOPART ) {
 309         return $e->die_event unless $e->allowed('TITLE_HOLDS', $porg);
 310     } elsif ( $t eq OILS_HOLD_TYPE_ISSUANCE ) {
 311         return $e->die_event unless $e->allowed('ISSUANCE_HOLDS', $porg);
 312     } elsif ( $t eq OILS_HOLD_TYPE_COPY ) {
 313         return $e->die_event unless $e->allowed('COPY_HOLDS',   $porg);
 314     } elsif ( $t eq OILS_HOLD_TYPE_FORCE || $t eq OILS_HOLD_TYPE_RECALL ) {
 315         my $copy = $e->retrieve_asset_copy($hold->target)
 316             or return $e->die_event;
 317         if ( $t eq OILS_HOLD_TYPE_FORCE ) {
 318             return $e->die_event unless $e->allowed('COPY_HOLDS_FORCE',   $copy->circ_lib);
 319         } elsif ( $t eq OILS_HOLD_TYPE_RECALL ) {
 320             return $e->die_event unless $e->allowed('COPY_HOLDS_RECALL',   $copy->circ_lib);
 321         }
 322     }
 323
 324     if( @events ) {
 325         if (!$override) {
 326             $e->rollback;
 327             return \@events;
 328         }
 329         for my $evt (@events) {
 330             next unless $evt;
 331             my $name = $evt->{textcode};
 332             if($oargs->{all} || grep { $_ eq $name } @{$oargs->{events}}) {
 333                 return $e->die_event unless $e->allowed("$name.override", $porg);
 334             } else {
 335                 $e->rollback;
 336                 return \@events;
 337             }
 338         }
 339     }
 340
 341         # Check for hold expiration in the past, and set it to empty string.
 342         $hold->expire_time(undef) if ($hold->expire_time && $U->datecmp($hold->expire_time) == -1);
 343
 344     # set the configured expire time
 345     unless($hold->expire_time) {
 346         $hold->expire_time(calculate_expire_time($recipient->home_ou));
 347     }
 348
 349
 350     # if behind-the-desk pickup is supported at the hold pickup lib,
 351     # set the value to the patron default, unless a value has already
 352     # been applied.  If it's not supported, force the value to false.
 353
 354     my $bdous = $U->ou_ancestor_setting_value(
 355         $hold->pickup_lib,
 356         'circ.holds.behind_desk_pickup_supported', $e);
 357
 358     if ($bdous) {
 359         if (!defined $hold->behind_desk) {
 360
 361             my $set = $e->search_actor_user_setting({
 362                 usr => $hold->usr,
 363                 name => 'circ.holds_behind_desk'
 364             })->[0];
 365
 366             $hold->behind_desk('t') if $set and
 367                 OpenSRF::Utils::JSON->JSON2perl($set->value);
 368         }
 369     } else {
 370         # behind the desk not supported, force it to false
 371         $hold->behind_desk('f');
 372     }
 373
 374     $hold->requestor($e->requestor->id);
 375     $hold->request_lib($e->requestor->ws_ou);
 376     $hold->selection_ou($hold->pickup_lib) unless $hold->selection_ou;
 377     $hold = $e->create_action_hold_request($hold) or return $e->die_event;
 378
 379     $e->commit;
 380
 381     $conn->respond_complete($hold->id);
 382
 383     $U->storagereq(
 384         'open-ils.storage.action.hold_request.copy_targeter',
 385         undef, $hold->id ) unless $U->is_true($hold->frozen);
 386
 387     return undef;
 388 }
 389
 390 # makes sure that a user has permission to place the type of requested hold
 391 # returns the Perm exception if not allowed, returns undef if all is well
 392 sub _check_holds_perm {
 393     my($type, $user_id, $org_id) = @_;
 394
 395     my $evt;
 396     if ($type eq "M") {
 397         $evt = $apputils->check_perms($user_id, $org_id, "MR_HOLDS"    );
 398     } elsif ($type eq "T") {
 399         $evt = $apputils->check_perms($user_id, $org_id, "TITLE_HOLDS" );
 400     } elsif($type eq "V") {
 401         $evt = $apputils->check_perms($user_id, $org_id, "VOLUME_HOLDS");
 402     } elsif($type eq "C") {
 403         $evt = $apputils->check_perms($user_id, $org_id, "COPY_HOLDS"  );
 404     }
 405
 406     return $evt if $evt;
 407     return undef;
 408 }
 409
 410 # tests if the given user is allowed to place holds on another's behalf
 411 sub _check_request_holds_perm {
 412     my $user_id = shift;
 413     my $org_id  = shift;
 414     if (my $evt = $apputils->check_perms(
 415         $user_id, $org_id, "REQUEST_HOLDS")) {
 416         return $evt;
 417     }
 418 }
 419
 420 my $ses_is_req_note = 'The login session is the requestor.  If the requestor is different from the user, ' .
 421                       'then the requestor must have VIEW_HOLD permissions';
 422
 423 __PACKAGE__->register_method(
 424     method    => "retrieve_holds_by_id",
 425     api_name  => "open-ils.circ.holds.retrieve_by_id",
 426     signature => {
 427         desc   => "Retrieve the hold, with hold transits attached, for the specified ID.  $ses_is_req_note",
 428         params => [
 429             { desc => 'Authentication token', type => 'string' },
 430             { desc => 'Hold ID',              type => 'number' }
 431         ],
 432         return => {
 433             desc => 'Hold object with transits attached, event on error',
 434         }
 435     }
 436 );
 437
 438
 439 sub retrieve_holds_by_id {
 440     my($self, $client, $auth, $hold_id) = @_;
 441     my $e = new_editor(authtoken=>$auth);
 442     $e->checkauth or return $e->event;
 443     $e->allowed('VIEW_HOLD') or return $e->event;
 444
 445     my $holds = $e->search_action_hold_request(
 446         [
 447             { id =>  $hold_id , fulfillment_time => undef },
 448             {
 449                 order_by => { ahr => "request_time" },
 450                 flesh => 1,
 451                 flesh_fields => {ahr => ['notes']}
 452             }
 453         ]
 454     );
 455
 456     flesh_hold_transits($holds);
 457     flesh_hold_notices($holds, $e);
 458     return $holds;
 459 }
 460
 461
 462 __PACKAGE__->register_method(
 463     method    => "retrieve_holds",
 464     api_name  => "open-ils.circ.holds.retrieve",
 465     signature => {
 466         desc   => "Retrieves all the holds, with hold transits attached, for the specified user.  $ses_is_req_note",
 467         params => [
 468             { desc => 'Authentication token', type => 'string'  },
 469             { desc => 'User ID',              type => 'integer' },
 470             { desc => 'Available Only',       type => 'boolean' }
 471         ],
 472         return => {
 473             desc => 'list of holds, event on error',
 474         }
 475    }
 476 );
 477
 478 __PACKAGE__->register_method(
 479     method        => "retrieve_holds",
 480     api_name      => "open-ils.circ.holds.id_list.retrieve",
 481     authoritative => 1,
 482     signature     => {
 483         desc   => "Retrieves all the hold IDs, for the specified user.  $ses_is_req_note",
 484         params => [
 485             { desc => 'Authentication token', type => 'string'  },
 486             { desc => 'User ID',              type => 'integer' },
 487             { desc => 'Available Only',       type => 'boolean' }
 488         ],
 489         return => {
 490             desc => 'list of holds, event on error',
 491         }
 492    }
 493 );
 494
 495 __PACKAGE__->register_method(
 496     method        => "retrieve_holds",
 497     api_name      => "open-ils.circ.holds.canceled.retrieve",
 498     authoritative => 1,
 499     signature     => {
 500         desc   => "Retrieves all the cancelled holds for the specified user.  $ses_is_req_note",
 501         params => [
 502             { desc => 'Authentication token', type => 'string'  },
 503             { desc => 'User ID',              type => 'integer' }
 504         ],
 505         return => {
 506             desc => 'list of holds, event on error',
 507         }
 508    }
 509 );
 510
 511 __PACKAGE__->register_method(
 512     method        => "retrieve_holds",
 513     api_name      => "open-ils.circ.holds.canceled.id_list.retrieve",
 514     authoritative => 1,
 515     signature     => {
 516         desc   => "Retrieves list of cancelled hold IDs for the specified user.  $ses_is_req_note",
 517         params => [
 518             { desc => 'Authentication token', type => 'string'  },
 519             { desc => 'User ID',              type => 'integer' }
 520         ],
 521         return => {
 522             desc => 'list of hold IDs, event on error',
 523         }
 524    }
 525 );
 526
 527
 528 sub retrieve_holds {
 529     my ($self, $client, $auth, $user_id, $available) = @_;
 530
 531     my $e = new_editor(authtoken=>$auth);
 532     return $e->event unless $e->checkauth;
 533     $user_id = $e->requestor->id unless defined $user_id;
 534
 535     my $notes_filter = {staff => 'f'};
 536     my $user = $e->retrieve_actor_user($user_id) or return $e->event;
 537     unless($user_id == $e->requestor->id) {
 538         if($e->allowed('VIEW_HOLD', $user->home_ou)) {
 539             $notes_filter = {staff => 't'}
 540         } else {
 541             my $allowed = OpenILS::Application::Actor::Friends->friend_perm_allowed(
 542                 $e, $user_id, $e->requestor->id, 'hold.view');
 543             return $e->event unless $allowed;
 544         }
 545     } else {
 546         # staff member looking at his/her own holds can see staff and non-staff notes
 547         $notes_filter = {} if $e->allowed('VIEW_HOLD', $user->home_ou);
 548     }
 549
 550     my $holds_query = {
 551         select => {ahr => ['id']},
 552         from => 'ahr',
 553         where => {usr => $user_id, fulfillment_time => undef}
 554     };
 555
 556     if($self->api_name =~ /canceled/) {
 557
 558         # Fetch the canceled holds
 559         # order cancelled holds by cancel time, most recent first
 560
 561         $holds_query->{order_by} = [{class => 'ahr', field => 'cancel_time', direction => 'desc'}];
 562
 563         my $cancel_age;
 564         my $cancel_count = $U->ou_ancestor_setting_value(
 565                 $e->requestor->ws_ou, 'circ.holds.canceled.display_count', $e);
 566
 567         unless($cancel_count) {
 568             $cancel_age = $U->ou_ancestor_setting_value(
 569                 $e->requestor->ws_ou, 'circ.holds.canceled.display_age', $e);
 570
 571             # if no settings are defined, default to last 10 cancelled holds
 572             $cancel_count = 10 unless $cancel_age;
 573         }
 574
 575         if($cancel_count) { # limit by count
 576
 577             $holds_query->{where}->{cancel_time} = {'!=' => undef};
 578             $holds_query->{limit} = $cancel_count;
 579
 580         } elsif($cancel_age) { # limit by age
 581
 582             # find all of the canceled holds that were canceled within the configured time frame
 583             my $date = DateTime->now->subtract(seconds => OpenSRF::Utils::interval_to_seconds($cancel_age));
 584             $date = $U->epoch2ISO8601($date->epoch);
 585             $holds_query->{where}->{cancel_time} = {'>=' => $date};
 586         }
 587
 588     } else {
 589
 590         # order non-cancelled holds by ready-for-pickup, then active, followed by suspended
 591         # "compare" sorts false values to the front.  testing pickup_lib != current_shelf_lib
 592         # will sort by pl = csl > pl != csl > followed by csl is null;
 593         $holds_query->{order_by} = [
 594             {   class => 'ahr',
 595                 field => 'pickup_lib',
 596                 compare => {'!='  => {'+ahr' => 'current_shelf_lib'}}},
 597             {class => 'ahr', field => 'shelf_time'},
 598             {class => 'ahr', field => 'frozen'},
 599             {class => 'ahr', field => 'request_time'}
 600
 601         ];
 602         $holds_query->{where}->{cancel_time} = undef;
 603         if($available) {
 604             $holds_query->{where}->{shelf_time} = {'!=' => undef};
 605             # Maybe?
 606             $holds_query->{where}->{pickup_lib} = {'=' => {'+ahr' => 'current_shelf_lib'}};
 607         }
 608     }
 609
 610     my $hold_ids = $e->json_query($holds_query);
 611     $hold_ids = [ map { $_->{id} } @$hold_ids ];
 612
 613     return $hold_ids if $self->api_name =~ /id_list/;
 614
 615     my @holds;
 616     for my $hold_id ( @$hold_ids ) {
 617
 618         my $hold = $e->retrieve_action_hold_request($hold_id);
 619         $hold->notes($e->search_action_hold_request_note({hold => $hold_id, %$notes_filter}));
 620
 621         $hold->transit(
 622             $e->search_action_hold_transit_copy([
 623                 {hold => $hold->id},
 624                 {order_by => {ahtc => 'source_send_time desc'}, limit => 1}])->[0]
 625         );
 626
 627         push(@holds, $hold);
 628     }
 629
 630     return \@holds;
 631 }
 632
 633
 634 __PACKAGE__->register_method(
 635     method   => 'user_hold_count',
 636     api_name => 'open-ils.circ.hold.user.count'
 637 );
 638
 639 sub user_hold_count {
 640     my ( $self, $conn, $auth, $userid ) = @_;
 641     my $e = new_editor( authtoken => $auth );
 642     return $e->event unless $e->checkauth;
 643     my $patron = $e->retrieve_actor_user($userid)
 644         or return $e->event;
 645     return $e->event unless $e->allowed( 'VIEW_HOLD', $patron->home_ou );
 646     return __user_hold_count( $self, $e, $userid );
 647 }
 648
 649 sub __user_hold_count {
 650     my ( $self, $e, $userid ) = @_;
 651     my $holds = $e->search_action_hold_request(
 652         {
 653             usr              => $userid,
 654             fulfillment_time => undef,
 655             cancel_time      => undef,
 656         },
 657         { idlist => 1 }
 658     );
 659
 660     return scalar(@$holds);
 661 }
 662
 663
 664 __PACKAGE__->register_method(
 665     method   => "retrieve_holds_by_pickup_lib",
 666     api_name => "open-ils.circ.holds.retrieve_by_pickup_lib",
 667     notes    =>
 668       "Retrieves all the holds, with hold transits attached, for the specified pickup_ou id."
 669 );
 670
 671 __PACKAGE__->register_method(
 672     method   => "retrieve_holds_by_pickup_lib",
 673     api_name => "open-ils.circ.holds.id_list.retrieve_by_pickup_lib",
 674     notes    => "Retrieves all the hold ids for the specified pickup_ou id. "
 675 );
 676
 677 sub retrieve_holds_by_pickup_lib {
 678     my ($self, $client, $login_session, $ou_id) = @_;
 679
 680     #FIXME -- put an appropriate permission check here
 681     #my( $user, $target, $evt ) = $apputils->checkses_requestor(
 682     #    $login_session, $user_id, 'VIEW_HOLD' );
 683     #return $evt if $evt;
 684
 685     my $holds = $apputils->simplereq(
 686         'open-ils.cstore',
 687         "open-ils.cstore.direct.action.hold_request.search.atomic",
 688         {
 689             pickup_lib =>  $ou_id ,
 690             fulfillment_time => undef,
 691             cancel_time => undef
 692         },
 693         { order_by => { ahr => "request_time" } }
 694     );
 695
 696     if ( ! $self->api_name =~ /id_list/ ) {
 697         flesh_hold_transits($holds);
 698         return $holds;
 699     }
 700     # else id_list
 701     return [ map { $_->id } @$holds ];
 702 }
 703
 704
 705 __PACKAGE__->register_method(
 706     method   => "uncancel_hold",
 707     api_name => "open-ils.circ.hold.uncancel"
 708 );
 709
 710 sub uncancel_hold {
 711     my($self, $client, $auth, $hold_id) = @_;
 712     my $e = new_editor(authtoken=>$auth, xact=>1);
 713     return $e->die_event unless $e->checkauth;
 714
 715     my $hold = $e->retrieve_action_hold_request($hold_id)
 716         or return $e->die_event;
 717     return $e->die_event unless $e->allowed('CANCEL_HOLDS', $hold->request_lib);
 718
 719     if ($hold->fulfillment_time) {
 720         $e->rollback;
 721         return 0;
 722     }
 723     unless ($hold->cancel_time) {
 724         $e->rollback;
 725         return 1;
 726     }
 727
 728     # if configured to reset the request time, also reset the expire time
 729     if($U->ou_ancestor_setting_value(
 730         $hold->request_lib, 'circ.holds.uncancel.reset_request_time', $e)) {
 731
 732         $hold->request_time('now');
 733         $hold->expire_time(calculate_expire_time($hold->request_lib));
 734     }
 735
 736     $hold->clear_cancel_time;
 737     $hold->clear_cancel_cause;
 738     $hold->clear_cancel_note;
 739     $hold->clear_shelf_time;
 740     $hold->clear_current_copy;
 741     $hold->clear_capture_time;
 742     $hold->clear_prev_check_time;
 743     $hold->clear_shelf_expire_time;
 744     $hold->clear_current_shelf_lib;
 745
 746     $e->update_action_hold_request($hold) or return $e->die_event;
 747     $e->commit;
 748
 749     $U->storagereq('open-ils.storage.action.hold_request.copy_targeter', undef, $hold_id);
 750
 751     return 1;
 752 }
 753
 754
 755 __PACKAGE__->register_method(
 756     method    => "cancel_hold",
 757     api_name  => "open-ils.circ.hold.cancel",
 758     signature => {
 759         desc   => 'Cancels the specified hold.  The login session is the requestor.  If the requestor is different from the usr field ' .
 760                   'on the hold, the requestor must have CANCEL_HOLDS permissions. The hold may be either the hold object or the hold id',
 761         param  => [
 762             {desc => 'Authentication token',  type => 'string'},
 763             {desc => 'Hold ID',               type => 'number'},
 764             {desc => 'Cause of Cancellation', type => 'string'},
 765             {desc => 'Note',                  type => 'string'}
 766         ],
 767         return => {
 768             desc => '1 on success, event on error'
 769         }
 770     }
 771 );
 772
 773 sub cancel_hold {
 774     my($self, $client, $auth, $holdid, $cause, $note) = @_;
 775
 776     my $e = new_editor(authtoken=>$auth, xact=>1);
 777     return $e->die_event unless $e->checkauth;
 778
 779     my $hold = $e->retrieve_action_hold_request($holdid)
 780         or return $e->die_event;
 781
 782     if( $e->requestor->id ne $hold->usr ) {
 783         return $e->die_event unless $e->allowed('CANCEL_HOLDS');
 784     }
 785
 786     if ($hold->cancel_time) {
 787         $e->rollback;
 788         return 1;
 789     }
 790
 791     # If the hold is captured, reset the copy status
 792     if( $hold->capture_time and $hold->current_copy ) {
 793
 794         my $copy = $e->retrieve_asset_copy($hold->current_copy)
 795             or return $e->die_event;
 796
 797         if( $copy->status == OILS_COPY_STATUS_ON_HOLDS_SHELF ) {
 798          $logger->info("canceling hold $holdid whose item is on the holds shelf");
 799 #            $logger->info("setting copy to status 'reshelving' on hold cancel");
 800 #            $copy->status(OILS_COPY_STATUS_RESHELVING);
 801 #            $copy->editor($e->requestor->id);
 802 #            $copy->edit_date('now');
 803 #            $e->update_asset_copy($copy) or return $e->event;
 804
 805         } elsif( $copy->status == OILS_COPY_STATUS_IN_TRANSIT ) {
 806
 807             my $hid = $hold->id;
 808             $logger->warn("! canceling hold [$hid] that is in transit");
 809             my $transid = $e->search_action_hold_transit_copy({hold=>$hold->id},{idlist=>1})->[0];
 810
 811             if( $transid ) {
 812                 my $trans = $e->retrieve_action_transit_copy($transid);
 813                 # Leave the transit alive, but  set the copy status to
 814                 # reshelving so it will be properly reshelved when it gets back home
 815                 if( $trans ) {
 816                     $trans->copy_status( OILS_COPY_STATUS_RESHELVING );
 817                     $e->update_action_transit_copy($trans) or return $e->die_event;
 818                 }
 819             }
 820         }
 821     }
 822
 823     $hold->cancel_time('now');
 824     $hold->cancel_cause($cause);
 825     $hold->cancel_note($note);
 826     $e->update_action_hold_request($hold)
 827         or return $e->die_event;
 828
 829     $e->commit;
 830
 831     # re-fetch the hold to pick up the real cancel_time (not "now") for A/T
 832     $e->xact_begin;
 833     $hold = $e->retrieve_action_hold_request($hold->id) or return $e->die_event;
 834     $e->rollback;
 835
 836     if ($e->requestor->id == $hold->usr) {
 837         $U->create_events_for_hook('hold_request.cancel.patron', $hold, $hold->pickup_lib);
 838     } else {
 839         $U->create_events_for_hook('hold_request.cancel.staff', $hold, $hold->pickup_lib);
 840     }
 841
 842     return 1;
 843 }
 844
 845 my $update_hold_desc = 'The login session is the requestor. '       .
 846    'If the requestor is different from the usr field on the hold, ' .
 847    'the requestor must have UPDATE_HOLDS permissions. '             .
 848    'If supplying a hash of hold data, "id" must be included. '      .
 849    'The hash is ignored if a hold object is supplied, '             .
 850    'so you should supply only one kind of hold data argument.'      ;
 851
 852 __PACKAGE__->register_method(
 853     method    => "update_hold",
 854     api_name  => "open-ils.circ.hold.update",
 855     signature => {
 856         desc   => "Updates the specified hold.  $update_hold_desc",
 857         params => [
 858             {desc => 'Authentication token',         type => 'string'},
 859             {desc => 'Hold Object',                  type => 'object'},
 860             {desc => 'Hash of values to be applied', type => 'object'}
 861         ],
 862         return => {
 863             desc => 'Hold ID on success, event on error',
 864             # type => 'number'
 865         }
 866     }
 867 );
 868
 869 __PACKAGE__->register_method(
 870     method    => "batch_update_hold",
 871     api_name  => "open-ils.circ.hold.update.batch",
 872     stream    => 1,
 873     signature => {
 874         desc   => "Updates the specified hold(s).  $update_hold_desc",
 875         params => [
 876             {desc => 'Authentication token',                    type => 'string'},
 877             {desc => 'Array of hold obejcts',                   type => 'array' },
 878             {desc => 'Array of hashes of values to be applied', type => 'array' }
 879         ],
 880         return => {
 881             desc => 'Hold ID per success, event per error',
 882         }
 883     }
 884 );
 885
 886 sub update_hold {
 887     my($self, $client, $auth, $hold, $values) = @_;
 888     my $e = new_editor(authtoken=>$auth, xact=>1);
 889     return $e->die_event unless $e->checkauth;
 890     my $resp = update_hold_impl($self, $e, $hold, $values);
 891     if ($U->event_code($resp)) {
 892         $e->rollback;
 893         return $resp;
 894     }
 895     $e->commit;     # FIXME: update_hold_impl already does $e->commit  ??
 896     return $resp;
 897 }
 898
 899 sub batch_update_hold {
 900     my($self, $client, $auth, $hold_list, $values_list) = @_;
 901     my $e = new_editor(authtoken=>$auth);
 902     return $e->die_event unless $e->checkauth;
 903
 904     my $count = ($hold_list) ? scalar(@$hold_list) : scalar(@$values_list);     # FIXME: we don't know for sure that we got $values_list.  we could have neither list.
 905     $hold_list   ||= [];
 906     $values_list ||= [];      # FIXME: either move this above $count declaration, or send an event if both lists undef.  Probably the latter.
 907
 908 # FIXME: Failing over to [] guarantees warnings for "Use of unitialized value" in update_hold_impl call.
 909 # FIXME: We should be sure we only call update_hold_impl with hold object OR hash, not both.
 910
 911     for my $idx (0..$count-1) {
 912         $e->xact_begin;
 913         my $resp = update_hold_impl($self, $e, $hold_list->[$idx], $values_list->[$idx]);
 914         $e->xact_commit unless $U->event_code($resp);
 915         $client->respond($resp);
 916     }
 917
 918     $e->disconnect;
 919     return undef;       # not in the register return type, assuming we should always have at least one list populated
 920 }
 921
 922 sub update_hold_impl {
 923     my($self, $e, $hold, $values) = @_;
 924     my $hold_status;
 925     my $need_retarget = 0;
 926
 927     unless($hold) {
 928         $hold = $e->retrieve_action_hold_request($values->{id})
 929             or return $e->die_event;
 930         for my $k (keys %$values) {
 931             # Outside of pickup_lib (covered by the first regex) I don't know when these would currently change.
 932             # But hey, why not cover things that may happen later?
 933             if ($k =~ '_(lib|ou)$' || $k eq 'target' || $k eq 'hold_type' || $k eq 'requestor' || $k eq 'selection_depth' || $k eq 'holdable_formats') {
 934                 if (defined $values->{$k} && defined $hold->$k() && $values->{$k} ne $hold->$k()) {
 935                     # Value changed? RETARGET!
 936                     $need_retarget = 1;
 937                 } elsif (defined $hold->$k() != defined $values->{$k}) {
 938                     # Value being set or cleared? RETARGET!
 939                     $need_retarget = 1;
 940                 }
 941             }
 942             if (defined $values->{$k}) {
 943                 $hold->$k($values->{$k});
 944             } else {
 945                 my $f = "clear_$k"; $hold->$f();
 946             }
 947         }
 948     }
 949
 950     my $orig_hold = $e->retrieve_action_hold_request($hold->id)
 951         or return $e->die_event;
 952
 953     # don't allow the user to be changed
 954     return OpenILS::Event->new('BAD_PARAMS') if $hold->usr != $orig_hold->usr;
 955
 956     if($hold->usr ne $e->requestor->id) {
 957         # if the hold is for a different user, make sure the
 958         # requestor has the appropriate permissions
 959         my $usr = $e->retrieve_actor_user($hold->usr)
 960             or return $e->die_event;
 961         return $e->die_event unless $e->allowed('UPDATE_HOLD', $usr->home_ou);
 962     }
 963
 964
 965     # --------------------------------------------------------------
 966     # Changing the request time is like playing God
 967     # --------------------------------------------------------------
 968     if($hold->request_time ne $orig_hold->request_time) {
 969         return OpenILS::Event->new('BAD_PARAMS') if $hold->fulfillment_time;
 970         return $e->die_event unless $e->allowed('UPDATE_HOLD_REQUEST_TIME', $hold->pickup_lib);
 971     }
 972
 973
 974     # --------------------------------------------------------------
 975     # Code for making sure staff have appropriate permissons for cut_in_line
 976     # This, as is, doesn't prevent a user from cutting their own holds in line
 977     # but needs to
 978     # --------------------------------------------------------------
 979     if($U->is_true($hold->cut_in_line) ne $U->is_true($orig_hold->cut_in_line)) {
 980         return $e->die_event unless $e->allowed('UPDATE_HOLD_REQUEST_TIME', $hold->pickup_lib);
 981     }
 982
 983
 984     # --------------------------------------------------------------
 985     # Disallow hold suspencion if the hold is already captured.
 986     # --------------------------------------------------------------
 987     if ($U->is_true($hold->frozen) and not $U->is_true($orig_hold->frozen)) {
 988         $hold_status = _hold_status($e, $hold);
 989         if ($hold_status > 2 && $hold_status != 7) { # hold is captured
 990             $logger->info("bypassing hold freeze on captured hold");
 991             return OpenILS::Event->new('HOLD_SUSPEND_AFTER_CAPTURE');
 992         }
 993     }
 994
 995
 996     # --------------------------------------------------------------
 997     # if the hold is on the holds shelf or in transit and the pickup
 998     # lib changes we need to create a new transit.
 999     # --------------------------------------------------------------
1000     if($orig_hold->pickup_lib ne $hold->pickup_lib) {
1001
1002         $hold_status = _hold_status($e, $hold) unless $hold_status;
1003
1004         if($hold_status == 3) { # in transit
1005
1006             return $e->die_event unless $e->allowed('UPDATE_PICKUP_LIB_FROM_TRANSIT', $orig_hold->pickup_lib);
1007             return $e->die_event unless $e->allowed('UPDATE_PICKUP_LIB_FROM_TRANSIT', $hold->pickup_lib);
1008
1009             $logger->info("updating pickup lib for hold ".$hold->id." while already in transit");
1010
1011             # update the transit to reflect the new pickup location
1012             my $transit = $e->search_action_hold_transit_copy(
1013                 {hold=>$hold->id, dest_recv_time => undef})->[0]
1014                 or return $e->die_event;
1015
1016             $transit->prev_dest($transit->dest); # mark the previous destination on the transit
1017             $transit->dest($hold->pickup_lib);
1018             $e->update_action_hold_transit_copy($transit) or return $e->die_event;
1019
1020         } elsif($hold_status == 4 or $hold_status == 5 or $hold_status == 8) { # on holds shelf
1021
1022             return $e->die_event unless $e->allowed('UPDATE_PICKUP_LIB_FROM_HOLDS_SHELF', $orig_hold->pickup_lib);
1023             return $e->die_event unless $e->allowed('UPDATE_PICKUP_LIB_FROM_HOLDS_SHELF', $hold->pickup_lib);
1024
1025             $logger->info("updating pickup lib for hold ".$hold->id." while on holds shelf");
1026
1027             if ($hold->pickup_lib eq $orig_hold->current_shelf_lib) {
1028                 # This can happen if the pickup lib is changed while the hold is
1029                 # on the shelf, then changed back to the original pickup lib.
1030                 # Restore the original shelf_expire_time to prevent abuse.
1031                 set_hold_shelf_expire_time(undef, $hold, $e, $hold->shelf_time);
1032
1033             } else {
1034                 # clear to prevent premature shelf expiration
1035                 $hold->clear_shelf_expire_time;
1036             }
1037         }
1038     }
1039
1040     if($U->is_true($hold->frozen)) {
1041         $logger->info("clearing current_copy and check_time for frozen hold ".$hold->id);
1042         $hold->clear_current_copy;
1043         $hold->clear_prev_check_time;
1044         # Clear expire_time to prevent frozen holds from expiring.
1045         $logger->info("clearing expire_time for frozen hold ".$hold->id);
1046         $hold->clear_expire_time;
1047     }
1048
1049     # If the hold_expire_time is in the past && is not equal to the
1050     # original expire_time, then reset the expire time to be in the
1051     # future.
1052     if ($hold->expire_time && $U->datecmp($hold->expire_time) == -1 && $U->datecmp($hold->expire_time, $orig_hold->expire_time) != 0) {
1053         $hold->expire_time(calculate_expire_time($hold->request_lib));
1054     }
1055
1056     # If the hold is reactivated, reset the expire_time.
1057     if(!$U->is_true($hold->frozen) && $U->is_true($orig_hold->frozen)) {
1058         $logger->info("Reset expire_time on activated hold ".$hold->id);
1059         $hold->expire_time(calculate_expire_time($hold->request_lib));
1060     }
1061
1062     $e->update_action_hold_request($hold) or return $e->die_event;
1063     $e->commit;
1064
1065     if(!$U->is_true($hold->frozen) && $U->is_true($orig_hold->frozen)) {
1066         $logger->info("Running targeter on activated hold ".$hold->id);
1067         $U->storagereq( 'open-ils.storage.action.hold_request.copy_targeter', undef, $hold->id );
1068     }
1069
1070     # a change to mint-condition changes the set of potential copies, so retarget the hold;
1071     if($U->is_true($hold->mint_condition) and !$U->is_true($orig_hold->mint_condition)) {
1072         _reset_hold($self, $e->requestor, $hold)
1073     } elsif($need_retarget && !defined $hold->capture_time()) { # If needed, retarget the hold due to changes
1074         $U->storagereq(
1075             'open-ils.storage.action.hold_request.copy_targeter', undef, $hold->id );
1076     }
1077
1078     return $hold->id;
1079 }
1080
1081 # this does not update the hold in the DB.  It only
1082 # sets the shelf_expire_time field on the hold object.
1083 # start_time is optional and defaults to 'now'
1084 sub set_hold_shelf_expire_time {
1085     my ($class, $hold, $editor, $start_time) = @_;
1086
1087     my $shelf_expire = $U->ou_ancestor_setting_value(
1088         $hold->pickup_lib,
1089         'circ.holds.default_shelf_expire_interval',
1090         $editor
1091     );
1092
1093     return undef unless $shelf_expire;
1094
1095     $start_time = ($start_time) ?
1096         DateTime::Format::ISO8601->new->parse_datetime(cleanse_ISO8601($start_time)) :
1097         DateTime->now(time_zone => 'local'); # without time_zone we get UTC ... yuck!
1098
1099     my $seconds = OpenSRF::Utils->interval_to_seconds($shelf_expire);
1100     my $expire_time = $start_time->add(seconds => $seconds);
1101
1102     # if the shelf expire time overlaps with a pickup lib's
1103     # closed date, push it out to the first open date
1104     my $dateinfo = $U->storagereq(
1105         'open-ils.storage.actor.org_unit.closed_date.overlap',
1106         $hold->pickup_lib, $expire_time->strftime('%FT%T%z'));
1107
1108     if($dateinfo) {
1109         my $dt_parser = DateTime::Format::ISO8601->new;
1110         $expire_time = $dt_parser->parse_datetime(cleanse_ISO8601($dateinfo->{end}));
1111
1112         # TODO: enable/disable time bump via setting?
1113         $expire_time->set(hour => '23', minute => '59', second => '59');
1114
1115         $logger->info("circulator: shelf_expire_time overlaps".
1116             " with closed date, pushing expire time to $expire_time");
1117     }
1118
1119     $hold->shelf_expire_time($expire_time->strftime('%FT%T%z'));
1120     return undef;
1121 }
1122
1123
1124 sub transit_hold {
1125     my($e, $orig_hold, $hold, $copy) = @_;
1126     my $src  = $orig_hold->pickup_lib;
1127     my $dest = $hold->pickup_lib;
1128
1129     $logger->info("putting hold into transit on pickup_lib update");
1130
1131     my $transit = Fieldmapper::action::hold_transit_copy->new;
1132     $transit->hold($hold->id);
1133     $transit->source($src);
1134     $transit->dest($dest);
1135     $transit->target_copy($copy->id);
1136     $transit->source_send_time('now');
1137     $transit->copy_status(OILS_COPY_STATUS_ON_HOLDS_SHELF);
1138
1139     $copy->status(OILS_COPY_STATUS_IN_TRANSIT);
1140     $copy->editor($e->requestor->id);
1141     $copy->edit_date('now');
1142
1143     $e->create_action_hold_transit_copy($transit) or return $e->die_event;
1144     $e->update_asset_copy($copy) or return $e->die_event;
1145     return undef;
1146 }
1147
1148 # if the hold is frozen, this method ensures that the hold is not "targeted",
1149 # that is, it clears the current_copy and prev_check_time to essentiallly
1150 # reset the hold.  If it is being activated, it runs the targeter in the background
1151 sub update_hold_if_frozen {
1152     my($self, $e, $hold, $orig_hold) = @_;
1153     return if $hold->capture_time;
1154
1155     if($U->is_true($hold->frozen)) {
1156         $logger->info("clearing current_copy and check_time for frozen hold ".$hold->id);
1157         $hold->clear_current_copy;
1158         $hold->clear_prev_check_time;
1159
1160     } else {
1161         if($U->is_true($orig_hold->frozen)) {
1162             $logger->info("Running targeter on activated hold ".$hold->id);
1163             $U->storagereq( 'open-ils.storage.action.hold_request.copy_targeter', undef, $hold->id );
1164         }
1165     }
1166 }
1167
1168 __PACKAGE__->register_method(
1169     method    => "hold_note_CUD",
1170     api_name  => "open-ils.circ.hold_request.note.cud",
1171     signature => {
1172         desc   => 'Create, update or delete a hold request note.  If the operator (from Auth. token) '
1173                 . 'is not the owner of the hold, the UPDATE_HOLD permission is required',
1174         params => [
1175             { desc => 'Authentication token', type => 'string' },
1176             { desc => 'Hold note object',     type => 'object' }
1177         ],
1178         return => {
1179             desc => 'Returns the note ID, event on error'
1180         },
1181     }
1182 );
1183
1184 sub hold_note_CUD {
1185     my($self, $conn, $auth, $note) = @_;
1186
1187     my $e = new_editor(authtoken => $auth, xact => 1);
1188     return $e->die_event unless $e->checkauth;
1189
1190     my $hold = $e->retrieve_action_hold_request($note->hold)
1191         or return $e->die_event;
1192
1193     if($hold->usr ne $e->requestor->id) {
1194         my $usr = $e->retrieve_actor_user($hold->usr);
1195         return $e->die_event unless $e->allowed('UPDATE_HOLD', $usr->home_ou);
1196         $note->staff('t') if $note->isnew;
1197     }
1198
1199     if($note->isnew) {
1200         $e->create_action_hold_request_note($note) or return $e->die_event;
1201     } elsif($note->ischanged) {
1202         $e->update_action_hold_request_note($note) or return $e->die_event;
1203     } elsif($note->isdeleted) {
1204         $e->delete_action_hold_request_note($note) or return $e->die_event;
1205     }
1206
1207     $e->commit;
1208     return $note->id;
1209 }
1210
1211
1212 __PACKAGE__->register_method(
1213     method    => "retrieve_hold_status",
1214     api_name  => "open-ils.circ.hold.status.retrieve",
1215     signature => {
1216         desc   => 'Calculates the current status of the hold. The requestor must have '      .
1217                   'VIEW_HOLD permissions if the hold is for a user other than the requestor' ,
1218         param  => [
1219             { desc => 'Hold ID', type => 'number' }
1220         ],
1221         return => {
1222             # type => 'number',     # event sometimes
1223             desc => <<'END_OF_DESC'
1224 Returns event on error or:
1225 -1 on error (for now),
1226  1 for 'waiting for copy to become available',
1227  2 for 'waiting for copy capture',
1228  3 for 'in transit',
1229  4 for 'arrived',
1230  5 for 'hold-shelf-delay'
1231  6 for 'canceled'
1232  7 for 'suspended'
1233  8 for 'captured, on wrong hold shelf'
1234  9 for 'fulfilled'
1235 END_OF_DESC
1236         }
1237     }
1238 );
1239
1240 sub retrieve_hold_status {
1241     my($self, $client, $auth, $hold_id) = @_;
1242
1243     my $e = new_editor(authtoken => $auth);
1244     return $e->event unless $e->checkauth;
1245     my $hold = $e->retrieve_action_hold_request($hold_id)
1246         or return $e->event;
1247
1248     if( $e->requestor->id != $hold->usr ) {
1249         return $e->event unless $e->allowed('VIEW_HOLD');
1250     }
1251
1252     return _hold_status($e, $hold);
1253
1254 }
1255
1256 sub _hold_status {
1257     my($e, $hold) = @_;
1258     if ($hold->cancel_time) {
1259         return 6;
1260     }
1261     if ($U->is_true($hold->frozen) && !$hold->capture_time) {
1262         return 7;
1263     }
1264     if ($hold->current_shelf_lib and $hold->current_shelf_lib ne $hold->pickup_lib) {
1265         return 8;
1266     }
1267     if ($hold->fulfillment_time) {
1268         return 9;
1269     }
1270     return 1 unless $hold->current_copy;
1271     return 2 unless $hold->capture_time;
1272
1273     my $copy = $hold->current_copy;
1274     unless( ref $copy ) {
1275         $copy = $e->retrieve_asset_copy($hold->current_copy)
1276             or return $e->event;
1277     }
1278
1279     return 3 if $copy->status == OILS_COPY_STATUS_IN_TRANSIT;
1280
1281     if($copy->status == OILS_COPY_STATUS_ON_HOLDS_SHELF) {
1282
1283         my $hs_wait_interval = $U->ou_ancestor_setting_value($hold->pickup_lib, 'circ.hold_shelf_status_delay');
1284         return 4 unless $hs_wait_interval;
1285
1286         # if a hold_shelf_status_delay interval is defined and start_time plus
1287         # the interval is greater than now, consider the hold to be in the virtual
1288         # "on its way to the holds shelf" status. Return 5.
1289
1290         my $transit    = $e->search_action_hold_transit_copy({
1291                             hold           => $hold->id,
1292                             target_copy    => $copy->id,
1293                             dest_recv_time => {'!=' => undef},
1294                          })->[0];
1295         my $start_time = ($transit) ? $transit->dest_recv_time : $hold->capture_time;
1296         $start_time    = DateTime::Format::ISO8601->new->parse_datetime(cleanse_ISO8601($start_time));
1297         my $end_time   = $start_time->add(seconds => OpenSRF::Utils::interval_to_seconds($hs_wait_interval));
1298
1299         return 5 if $end_time > DateTime->now;
1300         return 4;
1301     }
1302
1303     return -1;  # error
1304 }
1305
1306
1307
1308 __PACKAGE__->register_method(
1309     method    => "retrieve_hold_queue_stats",
1310     api_name  => "open-ils.circ.hold.queue_stats.retrieve",
1311     signature => {
1312         desc   => 'Returns summary data about the state of a hold',
1313         params => [
1314             { desc => 'Authentication token',  type => 'string'},
1315             { desc => 'Hold ID', type => 'number'},
1316         ],
1317         return => {
1318             desc => q/Summary object with keys:
1319                 total_holds : total holds in queue
1320                 queue_position : current queue position
1321                 potential_copies : number of potential copies for this hold
1322                 estimated_wait : estimated wait time in days
1323                 status : hold status
1324                      -1 => error or unexpected state,
1325                      1 => 'waiting for copy to become available',
1326                      2 => 'waiting for copy capture',
1327                      3 => 'in transit',
1328                      4 => 'arrived',
1329                      5 => 'hold-shelf-delay'
1330             /,
1331             type => 'object'
1332         }
1333     }
1334 );
1335
1336 sub retrieve_hold_queue_stats {
1337     my($self, $conn, $auth, $hold_id) = @_;
1338     my $e = new_editor(authtoken => $auth);
1339     return $e->event unless $e->checkauth;
1340     my $hold = $e->retrieve_action_hold_request($hold_id) or return $e->event;
1341     if($e->requestor->id != $hold->usr) {
1342         return $e->event unless $e->allowed('VIEW_HOLD');
1343     }
1344     return retrieve_hold_queue_status_impl($e, $hold);
1345 }
1346
1347 sub retrieve_hold_queue_status_impl {
1348     my $e = shift;
1349     my $hold = shift;
1350
1351     # The holds queue is defined as the distinct set of holds that share at
1352     # least one potential copy with the context hold, plus any holds that
1353     # share the same hold type and target.  The latter part exists to
1354     # accomodate holds that currently have no potential copies
1355     my $q_holds = $e->json_query({
1356
1357         # fetch cut_in_line and request_time since they're in the order_by
1358         # and we're asking for distinct values
1359         select => {ahr => ['id', 'cut_in_line', 'request_time']},
1360         from   => 'ahr',
1361         where => {
1362             id => { in => {
1363                 select => { ahcm => ['hold'] },
1364                 from   => {
1365                     'ahcm' => {
1366                         'ahcm2' => {
1367                             'class' => 'ahcm',
1368                             'field' => 'target_copy',
1369                             'fkey'  => 'target_copy'
1370                         }
1371                     }
1372                 },
1373                 where => { '+ahcm2' => { hold => $hold->id } },
1374                 distinct => 1
1375             }}
1376         },
1377         order_by => [
1378             {
1379                 "class" => "ahr",
1380                 "field" => "cut_in_line",
1381                 "transform" => "coalesce",
1382                 "params" => [ 0 ],
1383                 "direction" => "desc"
1384             },
1385             { "class" => "ahr", "field" => "request_time" }
1386         ],
1387         distinct => 1
1388     });
1389
1390     if (!@$q_holds) { # none? maybe we don't have a map ...
1391         $q_holds = $e->json_query({
1392             select => {ahr => ['id', 'cut_in_line', 'request_time']},
1393             from   => 'ahr',
1394             order_by => [
1395                 {
1396                     "class" => "ahr",
1397                     "field" => "cut_in_line",
1398                     "transform" => "coalesce",
1399                     "params" => [ 0 ],
1400                     "direction" => "desc"
1401                 },
1402                 { "class" => "ahr", "field" => "request_time" }
1403             ],
1404             where    => {
1405                 hold_type => $hold->hold_type,
1406                 target    => $hold->target,
1407                 capture_time => undef,
1408                 cancel_time => undef,
1409                 '-or' => [
1410                     {expire_time => undef },
1411                     {expire_time => {'>' => 'now'}}
1412                 ]
1413            }
1414         });
1415     }
1416
1417
1418     my $qpos = 1;
1419     for my $h (@$q_holds) {
1420         last if $h->{id} == $hold->id;
1421         $qpos++;
1422     }
1423
1424     my $hold_data = $e->json_query({
1425         select => {
1426             acp => [ {column => 'id', transform => 'count', aggregate => 1, alias => 'count'} ],
1427             ccm => [ {column =>'avg_wait_time'} ]
1428         },
1429         from => {
1430             ahcm => {
1431                 acp => {
1432                     join => {
1433                         ccm => {type => 'left'}
1434                     }
1435                 }
1436             }
1437         },
1438         where => {'+ahcm' => {hold => $hold->id} }
1439     });
1440
1441     my $user_org = $e->json_query({select => {au => ['home_ou']}, from => 'au', where => {id => $hold->usr}})->[0]->{home_ou};
1442
1443     my $default_wait = $U->ou_ancestor_setting_value($user_org, OILS_SETTING_HOLD_ESIMATE_WAIT_INTERVAL);
1444     my $min_wait = $U->ou_ancestor_setting_value($user_org, 'circ.holds.min_estimated_wait_interval');
1445     $min_wait = OpenSRF::Utils::interval_to_seconds($min_wait || '0 seconds');
1446     $default_wait ||= '0 seconds';
1447
1448     # Estimated wait time is the average wait time across the set
1449     # of potential copies, divided by the number of potential copies
1450     # times the queue position.
1451
1452     my $combined_secs = 0;
1453     my $num_potentials = 0;
1454
1455     for my $wait_data (@$hold_data) {
1456         my $count += $wait_data->{count};
1457         $combined_secs += $count *
1458             OpenSRF::Utils::interval_to_seconds($wait_data->{avg_wait_time} || $default_wait);
1459         $num_potentials += $count;
1460     }
1461
1462     my $estimated_wait = -1;
1463
1464     if($num_potentials) {
1465         my $avg_wait = $combined_secs / $num_potentials;
1466         $estimated_wait = $qpos * ($avg_wait / $num_potentials);
1467         $estimated_wait = $min_wait if $estimated_wait < $min_wait and $estimated_wait != -1;
1468     }
1469
1470     return {
1471         total_holds      => scalar(@$q_holds),
1472         queue_position   => $qpos,
1473         potential_copies => $num_potentials,
1474         status           => _hold_status( $e, $hold ),
1475         estimated_wait   => int($estimated_wait)
1476     };
1477 }
1478
1479
1480 sub fetch_open_hold_by_current_copy {
1481     my $class = shift;
1482     my $copyid = shift;
1483     my $hold = $apputils->simplereq(
1484         'open-ils.cstore',
1485         'open-ils.cstore.direct.action.hold_request.search.atomic',
1486         { current_copy =>  $copyid , cancel_time => undef, fulfillment_time => undef });
1487     return $hold->[0] if ref($hold);
1488     return undef;
1489 }
1490
1491 sub fetch_related_holds {
1492     my $class = shift;
1493     my $copyid = shift;
1494     return $apputils->simplereq(
1495         'open-ils.cstore',
1496         'open-ils.cstore.direct.action.hold_request.search.atomic',
1497         { current_copy =>  $copyid , cancel_time => undef, fulfillment_time => undef });
1498 }
1499
1500
1501 __PACKAGE__->register_method(
1502     method    => "hold_pull_list",
1503     api_name  => "open-ils.circ.hold_pull_list.retrieve",
1504     signature => {
1505         desc   => 'Returns (reference to) a list of holds that need to be "pulled" by a given location. ' .
1506                   'The location is determined by the login session.',
1507         params => [
1508             { desc => 'Limit (optional)',  type => 'number'},
1509             { desc => 'Offset (optional)', type => 'number'},
1510         ],
1511         return => {
1512             desc => 'reference to a list of holds, or event on failure',
1513         }
1514     }
1515 );
1516
1517 __PACKAGE__->register_method(
1518     method    => "hold_pull_list",
1519     api_name  => "open-ils.circ.hold_pull_list.id_list.retrieve",
1520     signature => {
1521         desc   => 'Returns (reference to) a list of holds IDs that need to be "pulled" by a given location. ' .
1522                   'The location is determined by the login session.',
1523         params => [
1524             { desc => 'Limit (optional)',  type => 'number'},
1525             { desc => 'Offset (optional)', type => 'number'},
1526         ],
1527         return => {
1528             desc => 'reference to a list of holds, or event on failure',
1529         }
1530     }
1531 );
1532
1533 __PACKAGE__->register_method(
1534     method    => "hold_pull_list",
1535     api_name  => "open-ils.circ.hold_pull_list.retrieve.count",
1536     signature => {
1537         desc   => 'Returns a count of holds that need to be "pulled" by a given location. ' .
1538                   'The location is determined by the login session.',
1539         params => [
1540             { desc => 'Limit (optional)',  type => 'number'},
1541             { desc => 'Offset (optional)', type => 'number'},
1542         ],
1543         return => {
1544             desc => 'Holds count (integer), or event on failure',
1545             # type => 'number'
1546         }
1547     }
1548 );
1549
1550 __PACKAGE__->register_method(
1551     method    => "hold_pull_list",
1552     stream => 1,
1553     # TODO: tag with api_level 2 once fully supported
1554     api_name  => "open-ils.circ.hold_pull_list.fleshed.stream",
1555     signature => {
1556         desc   => q/Returns a stream of fleshed holds  that need to be
1557                     "pulled" by a given location.  The location is
1558                     determined by the login session.
1559                     This API calls always run in authoritative mode./,
1560         params => [
1561             { desc => 'Limit (optional)',  type => 'number'},
1562             { desc => 'Offset (optional)', type => 'number'},
1563         ],
1564         return => {
1565             desc => 'Stream of holds holds, or event on failure',
1566         }
1567     }
1568 );
1569
1570 sub hold_pull_list {
1571     my( $self, $conn, $authtoken, $limit, $offset ) = @_;
1572     my( $reqr, $evt ) = $U->checkses($authtoken);
1573     return $evt if $evt;
1574
1575     my $org = $reqr->ws_ou || $reqr->home_ou;
1576     # the perm locaiton shouldn't really matter here since holds
1577     # will exist all over and VIEW_HOLDS should be universal
1578     $evt = $U->check_perms($reqr->id, $org, 'VIEW_HOLD');
1579     return $evt if $evt;
1580
1581     if($self->api_name =~ /count/) {
1582
1583         my $count = $U->storagereq(
1584             'open-ils.storage.direct.action.hold_request.pull_list.current_copy_circ_lib.status_filtered.count',
1585             $org, $limit, $offset );
1586
1587         $logger->info("Grabbing pull list for org unit $org with $count items");
1588         return $count;
1589
1590     } elsif( $self->api_name =~ /id_list/ ) {
1591         $U->storagereq(
1592             'open-ils.storage.direct.action.hold_request.pull_list.id_list.current_copy_circ_lib.status_filtered.atomic',
1593             $org, $limit, $offset );
1594
1595     } elsif ($self->api_name =~ /fleshed/) {
1596
1597         my $ids = $U->storagereq(
1598             'open-ils.storage.direct.action.hold_request.pull_list.id_list.current_copy_circ_lib.status_filtered.atomic',
1599             $org, $limit, $offset );
1600
1601         my $e = new_editor(xact => 1, requestor => $reqr);
1602         $conn->respond(uber_hold_impl($e, $_, {flesh_acpl => 1})) for @$ids;
1603         $e->rollback;
1604         $conn->respond_complete;
1605         return;
1606
1607     } else {
1608         $U->storagereq(
1609             'open-ils.storage.direct.action.hold_request.pull_list.search.current_copy_circ_lib.status_filtered.atomic',
1610             $org, $limit, $offset );
1611     }
1612 }
1613
1614 __PACKAGE__->register_method(
1615     method    => "print_hold_pull_list",
1616     api_name  => "open-ils.circ.hold_pull_list.print",
1617     signature => {
1618         desc   => 'Returns an HTML-formatted holds pull list',
1619         params => [
1620             { desc => 'Authtoken', type => 'string'},
1621             { desc => 'Org unit ID.  Optional, defaults to workstation org unit', type => 'number'},
1622         ],
1623         return => {
1624             desc => 'HTML string',
1625             type => 'string'
1626         }
1627     }
1628 );
1629
1630 sub print_hold_pull_list {
1631     my($self, $client, $auth, $org_id) = @_;
1632
1633     my $e = new_editor(authtoken=>$auth);
1634     return $e->event unless $e->checkauth;
1635
1636     $org_id = (defined $org_id) ? $org_id : $e->requestor->ws_ou;
1637     return $e->event unless $e->allowed('VIEW_HOLD', $org_id);
1638
1639     my $hold_ids = $U->storagereq(
1640         'open-ils.storage.direct.action.hold_request.pull_list.id_list.current_copy_circ_lib.status_filtered.atomic',
1641         $org_id, 10000);
1642
1643     return undef unless @$hold_ids;
1644
1645     $client->status(new OpenSRF::DomainObject::oilsContinueStatus);
1646
1647     # Holds will /NOT/ be in order after this ...
1648     my $holds = $e->search_action_hold_request({id => $hold_ids}, {substream => 1});
1649     $client->status(new OpenSRF::DomainObject::oilsContinueStatus);
1650
1651     # ... so we must resort.
1652     my $hold_map = +{map { $_->id => $_ } @$holds};
1653     my $sorted_holds = [];
1654     push @$sorted_holds, $hold_map->{$_} foreach @$hold_ids;
1655
1656     return $U->fire_object_event(
1657         undef, "ahr.format.pull_list", $sorted_holds,
1658         $org_id, undef, undef, $client
1659     );
1660
1661 }
1662
1663 __PACKAGE__->register_method(
1664     method    => "print_hold_pull_list_stream",
1665     stream   => 1,
1666     api_name  => "open-ils.circ.hold_pull_list.print.stream",
1667     signature => {
1668         desc   => 'Returns a stream of fleshed holds',
1669         params => [
1670             { desc => 'Authtoken', type => 'string'},
1671             { desc => 'Hash of optional param: Org unit ID (defaults to workstation org unit), limit, offset, sort (array of: acplo.position, prefix, call_number, suffix, request_time)',
1672               type => 'object'
1673             },
1674         ],
1675         return => {
1676             desc => 'A stream of fleshed holds',
1677             type => 'object'
1678         }
1679     }
1680 );
1681
1682 sub print_hold_pull_list_stream {
1683     my($self, $client, $auth, $params) = @_;
1684
1685     my $e = new_editor(authtoken=>$auth);
1686     return $e->die_event unless $e->checkauth;
1687
1688     delete($$params{org_id}) unless (int($$params{org_id}));
1689     delete($$params{limit}) unless (int($$params{limit}));
1690     delete($$params{offset}) unless (int($$params{offset}));
1691     delete($$params{chunk_size}) unless (int($$params{chunk_size}));
1692     delete($$params{chunk_size}) if  ($$params{chunk_size} && $$params{chunk_size} > 50); # keep the size reasonable
1693     $$params{chunk_size} ||= 10;
1694     $client->max_chunk_size($$params{chunk_size}) if ($client->can('max_chunk_size'));
1695
1696     $$params{org_id} = (defined $$params{org_id}) ? $$params{org_id}: $e->requestor->ws_ou;
1697     return $e->die_event unless $e->allowed('VIEW_HOLD', $$params{org_id });
1698
1699     my $sort = [];
1700     if ($$params{sort} && @{ $$params{sort} }) {
1701         for my $s (@{ $$params{sort} }) {
1702             if ($s eq 'acplo.position') {
1703                 push @$sort, {
1704                     "class" => "acplo", "field" => "position",
1705                     "transform" => "coalesce", "params" => [999]
1706                 };
1707             } elsif ($s eq 'prefix') {
1708                 push @$sort, {"class" => "acnp", "field" => "label_sortkey"};
1709             } elsif ($s eq 'call_number') {
1710                 push @$sort, {"class" => "acn", "field" => "label_sortkey"};
1711             } elsif ($s eq 'suffix') {
1712                 push @$sort, {"class" => "acns", "field" => "label_sortkey"};
1713             } elsif ($s eq 'request_time') {
1714                 push @$sort, {"class" => "ahr", "field" => "request_time"};
1715             }
1716         }
1717     } else {
1718         push @$sort, {"class" => "ahr", "field" => "request_time"};
1719     }
1720
1721     my $holds_ids = $e->json_query(
1722         {
1723             "select" => {"ahr" => ["id"]},
1724             "from" => {
1725                 "ahr" => {
1726                     "acp" => {
1727                         "field" => "id",
1728                         "fkey" => "current_copy",
1729                         "filter" => {
1730                             "circ_lib" => $$params{org_id}, "status" => [0,7]
1731                         },
1732                         "join" => {
1733                             "acn" => {
1734                                 "field" => "id",
1735                                 "fkey" => "call_number",
1736                                 "join" => {
1737                                     "acnp" => {
1738                                         "field" => "id",
1739                                         "fkey" => "prefix"
1740                                     },
1741                                     "acns" => {
1742                                         "field" => "id",
1743                                         "fkey" => "suffix"
1744                                     }
1745                                 }
1746                             },
1747                             "acplo" => {
1748                                 "field" => "org",
1749                                 "fkey" => "circ_lib",
1750                                 "type" => "left",
1751                                 "filter" => {
1752                                     "location" => {"=" => {"+acp" => "location"}}
1753                                 }
1754                             }
1755                         }
1756                     }
1757                 }
1758             },
1759             "where" => {
1760                 "+ahr" => {
1761                     "capture_time" => undef,
1762                     "cancel_time" => undef,
1763                     "-or" => [
1764                         {"expire_time" => undef },
1765                         {"expire_time" => {">" => "now"}}
1766                     ]
1767                 }
1768             },
1769             (@$sort ? (order_by => $sort) : ()),
1770             ($$params{limit} ? (limit => $$params{limit}) : ()),
1771             ($$params{offset} ? (offset => $$params{offset}) : ())
1772         }, {"substream" => 1}
1773     ) or return $e->die_event;
1774
1775     $logger->info("about to stream back " . scalar(@$holds_ids) . " holds");
1776
1777     my @chunk;
1778     for my $hid (@$holds_ids) {
1779         push @chunk, $e->retrieve_action_hold_request([
1780             $hid->{"id"}, {
1781                 "flesh" => 3,
1782                 "flesh_fields" => {
1783                     "ahr" => ["usr", "current_copy"],
1784                     "au"  => ["card"],
1785                     "acp" => ["location", "call_number", "parts"],
1786                     "acn" => ["record","prefix","suffix"]
1787                 }
1788             }
1789         ]);
1790
1791         if (@chunk >= $$params{chunk_size}) {
1792             $client->respond( \@chunk );
1793             @chunk = ();
1794         }
1795     }
1796     $client->respond_complete( \@chunk ) if (@chunk);
1797     $e->disconnect;
1798     return undef;
1799 }
1800
1801
1802
1803 __PACKAGE__->register_method(
1804     method        => 'fetch_hold_notify',
1805     api_name      => 'open-ils.circ.hold_notification.retrieve_by_hold',
1806     authoritative => 1,
1807     signature     => q/
1808 Returns a list of hold notification objects based on hold id.
1809 @param authtoken The loggin session key
1810 @param holdid The id of the hold whose notifications we want to retrieve
1811 @return An array of hold notification objects, event on error.
1812 /
1813 );
1814
1815 sub fetch_hold_notify {
1816     my( $self, $conn, $authtoken, $holdid ) = @_;
1817     my( $requestor, $evt ) = $U->checkses($authtoken);
1818     return $evt if $evt;
1819     my ($hold, $patron);
1820     ($hold, $evt) = $U->fetch_hold($holdid);
1821     return $evt if $evt;
1822     ($patron, $evt) = $U->fetch_user($hold->usr);
1823     return $evt if $evt;
1824
1825     $evt = $U->check_perms($requestor->id, $patron->home_ou, 'VIEW_HOLD_NOTIFICATION');
1826     return $evt if $evt;
1827
1828     $logger->info("User ".$requestor->id." fetching hold notifications for hold $holdid");
1829     return $U->cstorereq(
1830         'open-ils.cstore.direct.action.hold_notification.search.atomic', {hold => $holdid} );
1831 }
1832
1833
1834 __PACKAGE__->register_method(
1835     method    => 'create_hold_notify',
1836     api_name  => 'open-ils.circ.hold_notification.create',
1837     signature => q/
1838 Creates a new hold notification object
1839 @param authtoken The login session key
1840 @param notification The hold notification object to create
1841 @return ID of the new object on success, Event on error
1842 /
1843 );
1844
1845 sub create_hold_notify {
1846    my( $self, $conn, $auth, $note ) = @_;
1847    my $e = new_editor(authtoken=>$auth, xact=>1);
1848    return $e->die_event unless $e->checkauth;
1849
1850    my $hold = $e->retrieve_action_hold_request($note->hold)
1851       or return $e->die_event;
1852    my $patron = $e->retrieve_actor_user($hold->usr)
1853       or return $e->die_event;
1854
1855    return $e->die_event unless
1856       $e->allowed('CREATE_HOLD_NOTIFICATION', $patron->home_ou);
1857
1858    $note->notify_staff($e->requestor->id);
1859    $e->create_action_hold_notification($note) or return $e->die_event;
1860    $e->commit;
1861    return $note->id;
1862 }
1863
1864 __PACKAGE__->register_method(
1865     method    => 'create_hold_note',
1866     api_name  => 'open-ils.circ.hold_note.create',
1867     signature => q/
1868         Creates a new hold request note object
1869         @param authtoken The login session key
1870         @param note The hold note object to create
1871         @return ID of the new object on success, Event on error
1872         /
1873 );
1874
1875 sub create_hold_note {
1876    my( $self, $conn, $auth, $note ) = @_;
1877    my $e = new_editor(authtoken=>$auth, xact=>1);
1878    return $e->die_event unless $e->checkauth;
1879
1880    my $hold = $e->retrieve_action_hold_request($note->hold)
1881       or return $e->die_event;
1882    my $patron = $e->retrieve_actor_user($hold->usr)
1883       or return $e->die_event;
1884
1885    return $e->die_event unless
1886       $e->allowed('UPDATE_HOLD', $patron->home_ou); # FIXME: Using permcrud perm listed in fm_IDL.xml for ahrn.  Probably want something more specific
1887
1888    $e->create_action_hold_request_note($note) or return $e->die_event;
1889    $e->commit;
1890    return $note->id;
1891 }
1892
1893 __PACKAGE__->register_method(
1894     method    => 'reset_hold',
1895     api_name  => 'open-ils.circ.hold.reset',
1896     signature => q/
1897         Un-captures and un-targets a hold, essentially returning
1898         it to the state it was in directly after it was placed,
1899         then attempts to re-target the hold
1900         @param authtoken The login session key
1901         @param holdid The id of the hold
1902     /
1903 );
1904
1905
1906 sub reset_hold {
1907     my( $self, $conn, $auth, $holdid ) = @_;
1908     my $reqr;
1909     my ($hold, $evt) = $U->fetch_hold($holdid);
1910     return $evt if $evt;
1911     ($reqr, $evt) = $U->checksesperm($auth, 'UPDATE_HOLD');
1912     return $evt if $evt;
1913     $evt = _reset_hold($self, $reqr, $hold);
1914     return $evt if $evt;
1915     return 1;
1916 }
1917
1918
1919 __PACKAGE__->register_method(
1920     method   => 'reset_hold_batch',
1921     api_name => 'open-ils.circ.hold.reset.batch'
1922 );
1923
1924 sub reset_hold_batch {
1925     my($self, $conn, $auth, $hold_ids) = @_;
1926
1927     my $e = new_editor(authtoken => $auth);
1928     return $e->event unless $e->checkauth;
1929
1930     for my $hold_id ($hold_ids) {
1931
1932         my $hold = $e->retrieve_action_hold_request(
1933             [$hold_id, {flesh => 1, flesh_fields => {ahr => ['usr']}}])
1934             or return $e->event;
1935
1936         next unless $e->allowed('UPDATE_HOLD', $hold->usr->home_ou);
1937         _reset_hold($self, $e->requestor, $hold);
1938     }
1939
1940     return 1;
1941 }
1942
1943
1944 sub _reset_hold {
1945     my ($self, $reqr, $hold) = @_;
1946
1947     my $e = new_editor(xact =>1, requestor => $reqr);
1948
1949     $logger->info("reseting hold ".$hold->id);
1950
1951     my $hid = $hold->id;
1952
1953     if( $hold->capture_time and $hold->current_copy ) {
1954
1955         my $copy = $e->retrieve_asset_copy($hold->current_copy)
1956             or return $e->die_event;
1957
1958         if( $copy->status == OILS_COPY_STATUS_ON_HOLDS_SHELF ) {
1959             $logger->info("setting copy to status 'reshelving' on hold retarget");
1960             $copy->status(OILS_COPY_STATUS_RESHELVING);
1961             $copy->editor($e->requestor->id);
1962             $copy->edit_date('now');
1963             $e->update_asset_copy($copy) or return $e->die_event;
1964
1965         } elsif( $copy->status == OILS_COPY_STATUS_IN_TRANSIT ) {
1966
1967             # We don't want the copy to remain "in transit"
1968             $copy->status(OILS_COPY_STATUS_RESHELVING);
1969             $logger->warn("! reseting hold [$hid] that is in transit");
1970             my $transid = $e->search_action_hold_transit_copy({hold=>$hold->id},{idlist=>1})->[0];
1971
1972             if( $transid ) {
1973                 my $trans = $e->retrieve_action_transit_copy($transid);
1974                 if( $trans ) {
1975                     $logger->info("Aborting transit [$transid] on hold [$hid] reset...");
1976                     my $evt = OpenILS::Application::Circ::Transit::__abort_transit($e, $trans, $copy, 1, 1);
1977                     $logger->info("Transit abort completed with result $evt");
1978                     unless ("$evt" eq 1) {
1979                         $e->rollback;
1980                         return $evt;
1981                     }
1982                 }
1983             }
1984         }
1985     }
1986
1987     $hold->clear_capture_time;
1988     $hold->clear_current_copy;
1989     $hold->clear_shelf_time;
1990     $hold->clear_shelf_expire_time;
1991     $hold->clear_current_shelf_lib;
1992
1993     $e->update_action_hold_request($hold) or return $e->die_event;
1994     $e->commit;
1995
1996     $U->storagereq(
1997         'open-ils.storage.action.hold_request.copy_targeter', undef, $hold->id );
1998
1999     return undef;
2000 }
2001
2002
2003 __PACKAGE__->register_method(
2004     method    => 'fetch_open_title_holds',
2005     api_name  => 'open-ils.circ.open_holds.retrieve',
2006     signature => q/
2007         Returns a list ids of un-fulfilled holds for a given title id
2008         @param authtoken The login session key
2009         @param id the id of the item whose holds we want to retrieve
2010         @param type The hold type - M, T, I, V, C, F, R
2011     /
2012 );
2013
2014 sub fetch_open_title_holds {
2015     my( $self, $conn, $auth, $id, $type, $org ) = @_;
2016     my $e = new_editor( authtoken => $auth );
2017     return $e->event unless $e->checkauth;
2018
2019     $type ||= "T";
2020     $org  ||= $e->requestor->ws_ou;
2021
2022 #    return $e->search_action_hold_request(
2023 #        { target => $id, hold_type => $type, fulfillment_time => undef }, {idlist=>1});
2024
2025     # XXX make me return IDs in the future ^--
2026     my $holds = $e->search_action_hold_request(
2027         {
2028             target           => $id,
2029             cancel_time      => undef,
2030             hold_type        => $type,
2031             fulfillment_time => undef
2032         }
2033     );
2034
2035     flesh_hold_transits($holds);
2036     return $holds;
2037 }
2038
2039
2040 sub flesh_hold_transits {
2041     my $holds = shift;
2042     for my $hold ( @$holds ) {
2043         $hold->transit(
2044             $apputils->simplereq(
2045                 'open-ils.cstore',
2046                 "open-ils.cstore.direct.action.hold_transit_copy.search.atomic",
2047                 { hold => $hold->id },
2048                 { order_by => { ahtc => 'id desc' }, limit => 1 }
2049             )->[0]
2050         );
2051     }
2052 }
2053
2054 sub flesh_hold_notices {
2055     my( $holds, $e ) = @_;
2056     $e ||= new_editor();
2057
2058     for my $hold (@$holds) {
2059         my $notices = $e->search_action_hold_notification(
2060             [
2061                 { hold => $hold->id },
2062                 { order_by => { anh => 'notify_time desc' } },
2063             ],
2064             {idlist=>1}
2065         );
2066
2067         $hold->notify_count(scalar(@$notices));
2068         if( @$notices ) {
2069             my $n = $e->retrieve_action_hold_notification($$notices[0])
2070                 or return $e->event;
2071             $hold->notify_time($n->notify_time);
2072         }
2073     }
2074 }
2075
2076
2077 __PACKAGE__->register_method(
2078     method    => 'fetch_captured_holds',
2079     api_name  => 'open-ils.circ.captured_holds.on_shelf.retrieve',
2080     stream    => 1,
2081     authoritative => 1,
2082     signature => q/
2083         Returns a list of un-fulfilled holds (on the Holds Shelf) for a given title id
2084         @param authtoken The login session key
2085         @param org The org id of the location in question
2086         @param match_copy A specific copy to limit to
2087     /
2088 );
2089
2090 __PACKAGE__->register_method(
2091     method    => 'fetch_captured_holds',
2092     api_name  => 'open-ils.circ.captured_holds.id_list.on_shelf.retrieve',
2093     stream    => 1,
2094     authoritative => 1,
2095     signature => q/
2096         Returns list ids of un-fulfilled holds (on the Holds Shelf) for a given title id
2097         @param authtoken The login session key
2098         @param org The org id of the location in question
2099         @param match_copy A specific copy to limit to
2100     /
2101 );
2102
2103 __PACKAGE__->register_method(
2104     method    => 'fetch_captured_holds',
2105     api_name  => 'open-ils.circ.captured_holds.id_list.expired_on_shelf.retrieve',
2106     stream    => 1,
2107     authoritative => 1,
2108     signature => q/
2109         Returns list ids of shelf-expired un-fulfilled holds for a given title id
2110         @param authtoken The login session key
2111         @param org The org id of the location in question
2112         @param match_copy A specific copy to limit to
2113     /
2114 );
2115
2116 __PACKAGE__->register_method(
2117     method    => 'fetch_captured_holds',
2118     api_name  =>
2119       'open-ils.circ.captured_holds.expired_on_shelf_or_wrong_shelf.retrieve',
2120     stream    => 1,
2121     authoritative => 1,
2122     signature => q/
2123         Returns list of shelf-expired un-fulfilled holds OR wrong shelf holds
2124         for a given shelf lib
2125     /
2126 );
2127
2128 __PACKAGE__->register_method(
2129     method    => 'fetch_captured_holds',
2130     api_name  =>
2131       'open-ils.circ.captured_holds.id_list.expired_on_shelf_or_wrong_shelf.retrieve',
2132     stream    => 1,
2133     authoritative => 1,
2134     signature => q/
2135         Returns list of shelf-expired un-fulfilled holds OR wrong shelf holds
2136         for a given shelf lib
2137     /
2138 );
2139
2140
2141 sub fetch_captured_holds {
2142     my( $self, $conn, $auth, $org, $match_copy ) = @_;
2143
2144     my $e = new_editor(authtoken => $auth);
2145     return $e->die_event unless $e->checkauth;
2146     return $e->die_event unless $e->allowed('VIEW_HOLD'); # XXX rely on editor perm
2147
2148     $org ||= $e->requestor->ws_ou;
2149
2150     my $current_copy = { '!=' => undef };
2151     $current_copy = { '=' => $match_copy } if $match_copy;
2152
2153     my $query = {
2154         select => { alhr => ['id'] },
2155         from   => {
2156             alhr => {
2157                 acp => {
2158                     field => 'id',
2159                     fkey  => 'current_copy'
2160                 },
2161             }
2162         },
2163         where => {
2164             '+acp' => { status => OILS_COPY_STATUS_ON_HOLDS_SHELF, deleted => 'f' },
2165             '+alhr' => {
2166                 capture_time      => { "!=" => undef },
2167                 current_copy      => $current_copy,
2168                 fulfillment_time  => undef,
2169                 current_shelf_lib => $org
2170             }
2171         }
2172     };
2173     if($self->api_name =~ /expired/) {
2174         $query->{'where'}->{'+alhr'}->{'-or'} = {
2175                 shelf_expire_time => { '<' => 'today'},
2176                 cancel_time => { '!=' => undef },
2177         };
2178     }
2179     my $hold_ids = $e->json_query( $query );
2180
2181     if ($self->api_name =~ /wrong_shelf/) {
2182         # fetch holds whose current_shelf_lib is $org, but whose pickup
2183         # lib is some other org unit.  Ignore already-retrieved holds.
2184         my $wrong_shelf =
2185             pickup_lib_changed_on_shelf_holds(
2186                 $e, $org, [map {$_->{id}} @$hold_ids]);
2187         # match the layout of other items in $hold_ids
2188         push (@$hold_ids, {id => $_}) for @$wrong_shelf;
2189     }
2190
2191
2192     for my $hold_id (@$hold_ids) {
2193         if($self->api_name =~ /id_list/) {
2194             $conn->respond($hold_id->{id});
2195             next;
2196         } else {
2197             $conn->respond(
2198                 $e->retrieve_action_hold_request([
2199                     $hold_id->{id},
2200                     {
2201                         flesh => 1,
2202                         flesh_fields => {ahr => ['notifications', 'transit', 'notes']},
2203                         order_by => {anh => 'notify_time desc'}
2204                     }
2205                 ])
2206             );
2207         }
2208     }
2209
2210     return undef;
2211 }
2212
2213 __PACKAGE__->register_method(
2214     method    => "print_expired_holds_stream",
2215     api_name  => "open-ils.circ.captured_holds.expired.print.stream",
2216     stream    => 1
2217 );
2218
2219 sub print_expired_holds_stream {
2220     my ($self, $client, $auth, $params) = @_;
2221
2222     # No need to check specific permissions: we're going to call another method
2223     # that will do that.
2224     my $e = new_editor("authtoken" => $auth);
2225     return $e->die_event unless $e->checkauth;
2226
2227     delete($$params{org_id}) unless (int($$params{org_id}));
2228     delete($$params{limit}) unless (int($$params{limit}));
2229     delete($$params{offset}) unless (int($$params{offset}));
2230     delete($$params{chunk_size}) unless (int($$params{chunk_size}));
2231     delete($$params{chunk_size}) if  ($$params{chunk_size} && $$params{chunk_size} > 50); # keep the size reasonable
2232     $$params{chunk_size} ||= 10;
2233     $client->max_chunk_size($$params{chunk_size});
2234
2235     $$params{org_id} = (defined $$params{org_id}) ? $$params{org_id}: $e->requestor->ws_ou;
2236
2237     my @hold_ids = $self->method_lookup(
2238         "open-ils.circ.captured_holds.id_list.expired_on_shelf.retrieve"
2239     )->run($auth, $params->{"org_id"});
2240
2241     if (!@hold_ids) {
2242         $e->disconnect;
2243         return;
2244     } elsif (defined $U->event_code($hold_ids[0])) {
2245         $e->disconnect;
2246         return $hold_ids[0];
2247     }
2248
2249     $logger->info("about to stream back up to " . scalar(@hold_ids) . " expired holds");
2250
2251     while (@hold_ids) {
2252         my @hid_chunk = splice @hold_ids, 0, $params->{"chunk_size"};
2253
2254         my $result_chunk = $e->json_query({
2255             "select" => {
2256                 "acp" => ["barcode"],
2257                 "au" => [qw/
2258                     first_given_name second_given_name family_name alias
2259                 /],
2260                 "acn" => ["label"],
2261                 "bre" => ["marc"],
2262                 "acpl" => ["name"]
2263             },
2264             "from" => {
2265                 "ahr" => {
2266                     "acp" => {
2267                         "field" => "id", "fkey" => "current_copy",
2268                         "join" => {
2269                             "acn" => {
2270                                 "field" => "id", "fkey" => "call_number",
2271                                 "join" => {
2272                                     "bre" => {
2273                                         "field" => "id", "fkey" => "record"
2274                                     }
2275                                 }
2276                             },
2277                             "acpl" => {"field" => "id", "fkey" => "location"}
2278                         }
2279                     },
2280                     "au" => {"field" => "id", "fkey" => "usr"}
2281                 }
2282             },
2283             "where" => {"+ahr" => {"id" => \@hid_chunk}}
2284         }) or return $e->die_event;
2285         $client->respond($result_chunk);
2286     }
2287
2288     $e->disconnect;
2289     undef;
2290 }
2291
2292 __PACKAGE__->register_method(
2293     method    => "check_title_hold_batch",
2294     api_name  => "open-ils.circ.title_hold.is_possible.batch",
2295     stream    => 1,
2296     signature => {
2297         desc  => '@see open-ils.circ.title_hold.is_possible.batch',
2298         params => [
2299             { desc => 'Authentication token',     type => 'string'},
2300             { desc => 'Array of Hash of named parameters', type => 'array'},
2301         ],
2302         return => {
2303             desc => 'Array of response objects',
2304             type => 'array'
2305         }
2306     }
2307 );
2308
2309 sub check_title_hold_batch {
2310     my($self, $client, $authtoken, $param_list, $oargs) = @_;
2311     foreach (@$param_list) {
2312         my ($res) = $self->method_lookup('open-ils.circ.title_hold.is_possible')->run($authtoken, $_, $oargs);
2313         $client->respond($res);
2314     }
2315     return undef;
2316 }
2317
2318
2319 __PACKAGE__->register_method(
2320     method    => "check_title_hold",
2321     api_name  => "open-ils.circ.title_hold.is_possible",
2322     signature => {
2323         desc  => 'Determines if a hold were to be placed by a given user, ' .
2324              'whether or not said hold would have any potential copies to fulfill it.' .
2325              'The named paramaters of the second argument include: ' .
2326              'patronid, titleid, volume_id, copy_id, mrid, depth, pickup_lib, hold_type, selection_ou. ' .
2327              'See perldoc ' . __PACKAGE__ . ' for more info on these fields.' ,
2328         params => [
2329             { desc => 'Authentication token',     type => 'string'},
2330             { desc => 'Hash of named parameters', type => 'object'},
2331         ],
2332         return => {
2333             desc => 'List of new message IDs (empty if none)',
2334             type => 'array'
2335         }
2336     }
2337 );
2338
2339 =head3 check_title_hold (token, hash)
2340
2341 The named fields in the hash are:
2342
2343  patronid     - ID of the hold recipient  (required)
2344  depth        - hold range depth          (default 0)
2345  pickup_lib   - destination for hold, fallback value for selection_ou
2346  selection_ou - ID of org_unit establishing hard and soft hold boundary settings
2347  issuanceid   - ID of the issuance to be held, required for Issuance level hold
2348  partid       - ID of the monograph part to be held, required for monograph part level hold
2349  titleid      - ID (BRN) of the title to be held, required for Title level hold
2350  volume_id    - required for Volume level hold
2351  copy_id      - required for Copy level hold
2352  mrid         - required for Meta-record level hold
2353  hold_type    - T, C (or R or F), I, V or M for Title, Copy, Issuance, Volume or Meta-record  (default "T")
2354
2355 All key/value pairs are passed on to do_possibility_checks.
2356
2357 =cut
2358
2359 # FIXME: better params checking.  what other params are required, if any?
2360 # FIXME: 3 copies of values confusing: $x, $params->{x} and $params{x}
2361 # FIXME: for example, $depth gets a default value, but then $$params{depth} is still
2362 # used in conditionals, where it may be undefined, causing a warning.
2363 # FIXME: specify proper usage/interaction of selection_ou and pickup_lib
2364
2365 sub check_title_hold {
2366     my( $self, $client, $authtoken, $params ) = @_;
2367     my $e = new_editor(authtoken=>$authtoken);
2368     return $e->event unless $e->checkauth;
2369
2370     my %params       = %$params;
2371     my $depth        = $params{depth}        || 0;
2372     my $selection_ou = $params{selection_ou} || $params{pickup_lib};
2373     my $oargs        = $params{oargs}        || {};
2374
2375     if($oargs->{events}) {
2376         @{$oargs->{events}} = grep { $e->allowed($_ . '.override', $e->requestor->ws_ou); } @{$oargs->{events}};
2377     }
2378
2379
2380     my $patron = $e->retrieve_actor_user($params{patronid})
2381         or return $e->event;
2382
2383     if( $e->requestor->id ne $patron->id ) {
2384         return $e->event unless
2385             $e->allowed('VIEW_HOLD_PERMIT', $patron->home_ou);
2386     }
2387
2388     return OpenILS::Event->new('PATRON_BARRED') if $U->is_true($patron->barred);
2389
2390     my $request_lib = $e->retrieve_actor_org_unit($e->requestor->ws_ou)
2391         or return $e->event;
2392
2393     my $soft_boundary = $U->ou_ancestor_setting_value($selection_ou, OILS_SETTING_HOLD_SOFT_BOUNDARY);
2394     my $hard_boundary = $U->ou_ancestor_setting_value($selection_ou, OILS_SETTING_HOLD_HARD_BOUNDARY);
2395
2396     my @status = ();
2397     my $return_depth = $hard_boundary; # default depth to return on success
2398     if(defined $soft_boundary and $depth < $soft_boundary) {
2399         # work up the tree and as soon as we find a potential copy, use that depth
2400         # also, make sure we don't go past the hard boundary if it exists
2401
2402         # our min boundary is the greater of user-specified boundary or hard boundary
2403         my $min_depth = (defined $hard_boundary and $hard_boundary > $depth) ?
2404             $hard_boundary : $depth;
2405
2406         my $depth = $soft_boundary;
2407         while($depth >= $min_depth) {
2408             $logger->info("performing hold possibility check with soft boundary $depth");
2409             @status = do_possibility_checks($e, $patron, $request_lib, $depth, %params);
2410             if ($status[0]) {
2411                 $return_depth = $depth;
2412                 last;
2413             }
2414             $depth--;
2415         }
2416     } elsif(defined $hard_boundary and $depth < $hard_boundary) {
2417         # there is no soft boundary, enforce the hard boundary if it exists
2418         $logger->info("performing hold possibility check with hard boundary $hard_boundary");
2419         @status = do_possibility_checks($e, $patron, $request_lib, $hard_boundary, %params);
2420     } else {
2421         # no boundaries defined, fall back to user specifed boundary or no boundary
2422         $logger->info("performing hold possibility check with no boundary");
2423         @status = do_possibility_checks($e, $patron, $request_lib, $params{depth}, %params);
2424     }
2425
2426     my $place_unfillable = 0;
2427     $place_unfillable = 1 if $e->allowed('PLACE_UNFILLABLE_HOLD', $e->requestor->ws_ou);
2428
2429     if ($status[0]) {
2430         return {
2431             "success" => 1,
2432             "depth" => $return_depth,
2433             "local_avail" => $status[1]
2434         };
2435     } elsif ($status[2]) {
2436         my $n = scalar @{$status[2]};
2437         return {"success" => 0, "last_event" => $status[2]->[$n - 1], "age_protected_copy" => $status[3], "place_unfillable" => $place_unfillable};
2438     } else {
2439         return {"success" => 0, "age_protected_copy" => $status[3], "place_unfillable" => $place_unfillable};
2440     }
2441 }
2442
2443
2444
2445 sub do_possibility_checks {
2446     my($e, $patron, $request_lib, $depth, %params) = @_;
2447
2448     my $issuanceid   = $params{issuanceid}      || "";
2449     my $partid       = $params{partid}      || "";
2450     my $titleid      = $params{titleid}      || "";
2451     my $volid        = $params{volume_id};
2452     my $copyid       = $params{copy_id};
2453     my $mrid         = $params{mrid}         || "";
2454     my $pickup_lib   = $params{pickup_lib};
2455     my $hold_type    = $params{hold_type}    || 'T';
2456     my $selection_ou = $params{selection_ou} || $pickup_lib;
2457     my $holdable_formats = $params{holdable_formats};
2458     my $oargs        = $params{oargs}        || {};
2459
2460
2461     my $copy;
2462     my $volume;
2463     my $title;
2464
2465     if( $hold_type eq OILS_HOLD_TYPE_FORCE || $hold_type eq OILS_HOLD_TYPE_RECALL || $hold_type eq OILS_HOLD_TYPE_COPY ) {
2466
2467         return $e->event unless $copy   = $e->retrieve_asset_copy($copyid);
2468         return $e->event unless $volume = $e->retrieve_asset_call_number($copy->call_number);
2469         return $e->event unless $title  = $e->retrieve_biblio_record_entry($volume->record);
2470
2471         return (1, 1, []) if( $hold_type eq OILS_HOLD_TYPE_RECALL || $hold_type eq OILS_HOLD_TYPE_FORCE);
2472         return verify_copy_for_hold(
2473             $patron, $e->requestor, $title, $copy, $pickup_lib, $request_lib, $oargs
2474         );
2475
2476     } elsif( $hold_type eq OILS_HOLD_TYPE_VOLUME ) {
2477
2478         return $e->event unless $volume = $e->retrieve_asset_call_number($volid);
2479         return $e->event unless $title  = $e->retrieve_biblio_record_entry($volume->record);
2480
2481         return _check_volume_hold_is_possible(
2482             $volume, $title, $depth, $request_lib, $patron, $e->requestor, $pickup_lib, $selection_ou, $oargs
2483         );
2484
2485     } elsif( $hold_type eq OILS_HOLD_TYPE_TITLE ) {
2486
2487         return _check_title_hold_is_possible(
2488             $titleid, $depth, $request_lib, $patron, $e->requestor, $pickup_lib, $selection_ou, undef, $oargs
2489         );
2490
2491     } elsif( $hold_type eq OILS_HOLD_TYPE_ISSUANCE ) {
2492
2493         return _check_issuance_hold_is_possible(
2494             $issuanceid, $depth, $request_lib, $patron, $e->requestor, $pickup_lib, $selection_ou, $oargs
2495         );
2496
2497     } elsif( $hold_type eq OILS_HOLD_TYPE_MONOPART ) {
2498
2499         return _check_monopart_hold_is_possible(
2500             $partid, $depth, $request_lib, $patron, $e->requestor, $pickup_lib, $selection_ou, $oargs
2501         );
2502
2503     } elsif( $hold_type eq OILS_HOLD_TYPE_METARECORD ) {
2504
2505         # pasing undef as the depth to filtered_records causes the depth
2506         # of the selection_ou to be used, which is not what we want here.
2507         $depth ||= 0;
2508
2509         my ($recs) = __PACKAGE__->method_lookup('open-ils.circ.holds.metarecord.filtered_records')->run($mrid, $holdable_formats, $selection_ou, $depth);
2510         my @status = ();
2511         for my $rec (@$recs) {
2512             @status = _check_title_hold_is_possible(
2513                 $rec, $depth, $request_lib, $patron, $e->requestor, $pickup_lib, $selection_ou, $holdable_formats, $oargs
2514             );
2515             last if $status[0];
2516         }
2517         return @status;
2518     }
2519 #   else { Unrecognized hold_type ! }   # FIXME: return error? or 0?
2520 }
2521
2522 sub MR_filter_records {
2523     my $self = shift;
2524     my $client = shift;
2525     my $m = shift;
2526     my $f = shift;
2527     my $o = shift;
2528     my $d = shift;
2529     my $opac_visible = shift;
2530
2531     my $org_at_depth = defined($d) ? $U->org_unit_ancestor_at_depth($o, $d) : $o;
2532     return $U->storagereq(
2533         'open-ils.storage.metarecord.filtered_records.atomic',
2534         $m, $f, $org_at_depth, $opac_visible
2535     );
2536 }
2537 __PACKAGE__->register_method(
2538     method   => 'MR_filter_records',
2539     api_name => 'open-ils.circ.holds.metarecord.filtered_records',
2540 );
2541
2542
2543 my %prox_cache;
2544 sub create_ranged_org_filter {
2545     my($e, $selection_ou, $depth) = @_;
2546
2547     # find the orgs from which this hold may be fulfilled,
2548     # based on the selection_ou and depth
2549
2550     my $top_org = $e->search_actor_org_unit([
2551         {parent_ou => undef},
2552         {flesh=>1, flesh_fields=>{aou=>['ou_type']}}])->[0];
2553     my %org_filter;
2554
2555     return () if $depth == $top_org->ou_type->depth;
2556
2557     my $org_list = $U->storagereq('open-ils.storage.actor.org_unit.descendants.atomic', $selection_ou, $depth);
2558     %org_filter = (circ_lib => []);
2559     push(@{$org_filter{circ_lib}}, $_->id) for @$org_list;
2560
2561     $logger->info("hold org filter at depth $depth and selection_ou ".
2562         "$selection_ou created list of @{$org_filter{circ_lib}}");
2563
2564     return %org_filter;
2565 }
2566
2567
2568 sub _check_title_hold_is_possible {
2569     my( $titleid, $depth, $request_lib, $patron, $requestor, $pickup_lib, $selection_ou, $holdable_formats, $oargs ) = @_;
2570     # $holdable_formats is now unused. We pre-filter the MR's records.
2571
2572     my $e = new_editor();
2573     my %org_filter = create_ranged_org_filter($e, $selection_ou, $depth);
2574
2575     # this monster will grab the id and circ_lib of all of the "holdable" copies for the given record
2576     my $copies = $e->json_query(
2577         {
2578             select => { acp => ['id', 'circ_lib'] },
2579               from => {
2580                 acp => {
2581                     acn => {
2582                         field  => 'id',
2583                         fkey   => 'call_number',
2584                         filter => { record => $titleid }
2585                     },
2586                     acpl => {
2587                                 field => 'id',
2588                                 filter => { holdable => 't', deleted => 'f' },
2589                                 fkey => 'location'
2590                             },
2591                     ccs  => { field => 'id', filter => { holdable => 't'}, fkey => 'status'   },
2592                     acpm => { field => 'target_copy', type => 'left' } # ignore part-linked copies
2593                 }
2594             },
2595             where => {
2596                 '+acp' => { circulate => 't', deleted => 'f', holdable => 't', %org_filter },
2597                 '+acpm' => { target_copy => undef } # ignore part-linked copies
2598             }
2599         }
2600     );
2601
2602     $logger->info("title possible found ".scalar(@$copies)." potential copies");
2603     return (
2604         0, 0, [
2605             new OpenILS::Event(
2606                 "HIGH_LEVEL_HOLD_HAS_NO_COPIES",
2607                 "payload" => {"fail_part" => "no_ultimate_items"}
2608             )
2609         ]
2610     ) unless @$copies;
2611
2612     # -----------------------------------------------------------------------
2613     # sort the copies into buckets based on their circ_lib proximity to
2614     # the patron's home_ou.
2615     # -----------------------------------------------------------------------
2616
2617     my $home_org = $patron->home_ou;
2618     my $req_org = $request_lib->id;
2619
2620     $logger->info("prox cache $home_org " . $prox_cache{$home_org});
2621
2622     $prox_cache{$home_org} =
2623         $e->search_actor_org_unit_proximity({from_org => $home_org})
2624         unless $prox_cache{$home_org};
2625     my $home_prox = $prox_cache{$home_org};
2626
2627     my %buckets;
2628     my %hash = map { ($_->to_org => $_->prox) } @$home_prox;
2629     push( @{$buckets{ $hash{$_->{circ_lib}} } }, $_->{id} ) for @$copies;
2630
2631     my @keys = sort { $a <=> $b } keys %buckets;
2632
2633
2634     if( $home_org ne $req_org ) {
2635       # -----------------------------------------------------------------------
2636       # shove the copies close to the request_lib into the primary buckets
2637       # directly before the farthest away copies.  That way, they are not
2638       # given priority, but they are checked before the farthest copies.
2639       # -----------------------------------------------------------------------
2640         $prox_cache{$req_org} =
2641             $e->search_actor_org_unit_proximity({from_org => $req_org})
2642             unless $prox_cache{$req_org};
2643         my $req_prox = $prox_cache{$req_org};
2644
2645         my %buckets2;
2646         my %hash2 = map { ($_->to_org => $_->prox) } @$req_prox;
2647         push( @{$buckets2{ $hash2{$_->{circ_lib}} } }, $_->{id} ) for @$copies;
2648
2649         my $highest_key = $keys[@keys - 1];  # the farthest prox in the exising buckets
2650         my $new_key = $highest_key - 0.5; # right before the farthest prox
2651         my @keys2   = sort { $a <=> $b } keys %buckets2;
2652         for my $key (@keys2) {
2653             last if $key >= $highest_key;
2654             push( @{$buckets{$new_key}}, $_ ) for @{$buckets2{$key}};
2655         }
2656     }
2657
2658     @keys = sort { $a <=> $b } keys %buckets;
2659
2660     my $title;
2661     my %seen;
2662     my @status;
2663     my $age_protect_only = 0;
2664     OUTER: for my $key (@keys) {
2665       my @cps = @{$buckets{$key}};
2666
2667       $logger->info("looking at " . scalar(@{$buckets{$key}}). " copies in proximity bucket $key");
2668
2669       for my $copyid (@cps) {
2670
2671          next if $seen{$copyid};
2672          $seen{$copyid} = 1; # there could be dupes given the merged buckets
2673          my $copy = $e->retrieve_asset_copy($copyid);
2674          $logger->debug("looking at bucket_key=$key, copy $copyid : circ_lib = " . $copy->circ_lib);
2675
2676          unless($title) { # grab the title if we don't already have it
2677             my $vol = $e->retrieve_asset_call_number(
2678                [ $copy->call_number, { flesh => 1, flesh_fields => { bre => ['fixed_fields'], acn => ['record'] } } ] );
2679             $title = $vol->record;
2680          }
2681
2682          @status = verify_copy_for_hold(
2683             $patron, $requestor, $title, $copy, $pickup_lib, $request_lib, $oargs);
2684
2685          $age_protect_only ||= $status[3];
2686          last OUTER if $status[0];
2687       }
2688     }
2689
2690     $status[3] = $age_protect_only;
2691     return @status;
2692 }
2693
2694 sub _check_issuance_hold_is_possible {
2695     my( $issuanceid, $depth, $request_lib, $patron, $requestor, $pickup_lib, $selection_ou, $oargs ) = @_;
2696
2697     my $e = new_editor();
2698     my %org_filter = create_ranged_org_filter($e, $selection_ou, $depth);
2699
2700     # this monster will grab the id and circ_lib of all of the "holdable" copies for the given record
2701     my $copies = $e->json_query(
2702         {
2703             select => { acp => ['id', 'circ_lib'] },
2704               from => {
2705                 acp => {
2706                     sitem => {
2707                         field  => 'unit',
2708                         fkey   => 'id',
2709                         filter => { issuance => $issuanceid }
2710                     },
2711                     acpl => {
2712                         field => 'id',
2713                         filter => { holdable => 't', deleted => 'f' },
2714                         fkey => 'location'
2715                     },
2716                     ccs  => { field => 'id', filter => { holdable => 't'}, fkey => 'status'   }
2717                 }
2718             },
2719             where => {
2720                 '+acp' => { circulate => 't', deleted => 'f', holdable => 't', %org_filter }
2721             },
2722             distinct => 1
2723         }
2724     );
2725
2726     $logger->info("issuance possible found ".scalar(@$copies)." potential copies");
2727
2728     my $empty_ok;
2729     if (!@$copies) {
2730         $empty_ok = $e->retrieve_config_global_flag('circ.holds.empty_issuance_ok');
2731         $empty_ok = ($empty_ok and $U->is_true($empty_ok->enabled));
2732
2733         return (
2734             0, 0, [
2735                 new OpenILS::Event(
2736                     "HIGH_LEVEL_HOLD_HAS_NO_COPIES",
2737                     "payload" => {"fail_part" => "no_ultimate_items"}
2738                 )
2739             ]
2740         ) unless $empty_ok;
2741
2742         return (1, 0);
2743     }
2744
2745     # -----------------------------------------------------------------------
2746     # sort the copies into buckets based on their circ_lib proximity to
2747     # the patron's home_ou.
2748     # -----------------------------------------------------------------------
2749
2750     my $home_org = $patron->home_ou;
2751     my $req_org = $request_lib->id;
2752
2753     $logger->info("prox cache $home_org " . $prox_cache{$home_org});
2754
2755     $prox_cache{$home_org} =
2756         $e->search_actor_org_unit_proximity({from_org => $home_org})
2757         unless $prox_cache{$home_org};
2758     my $home_prox = $prox_cache{$home_org};
2759
2760     my %buckets;
2761     my %hash = map { ($_->to_org => $_->prox) } @$home_prox;
2762     push( @{$buckets{ $hash{$_->{circ_lib}} } }, $_->{id} ) for @$copies;
2763
2764     my @keys = sort { $a <=> $b } keys %buckets;
2765
2766
2767     if( $home_org ne $req_org ) {
2768       # -----------------------------------------------------------------------
2769       # shove the copies close to the request_lib into the primary buckets
2770       # directly before the farthest away copies.  That way, they are not
2771       # given priority, but they are checked before the farthest copies.
2772       # -----------------------------------------------------------------------
2773         $prox_cache{$req_org} =
2774             $e->search_actor_org_unit_proximity({from_org => $req_org})
2775             unless $prox_cache{$req_org};
2776         my $req_prox = $prox_cache{$req_org};
2777
2778         my %buckets2;
2779         my %hash2 = map { ($_->to_org => $_->prox) } @$req_prox;
2780         push( @{$buckets2{ $hash2{$_->{circ_lib}} } }, $_->{id} ) for @$copies;
2781
2782         my $highest_key = $keys[@keys - 1];  # the farthest prox in the exising buckets
2783         my $new_key = $highest_key - 0.5; # right before the farthest prox
2784         my @keys2   = sort { $a <=> $b } keys %buckets2;
2785         for my $key (@keys2) {
2786             last if $key >= $highest_key;
2787             push( @{$buckets{$new_key}}, $_ ) for @{$buckets2{$key}};
2788         }
2789     }
2790
2791     @keys = sort { $a <=> $b } keys %buckets;
2792
2793     my $title;
2794     my %seen;
2795     my @status;
2796     my $age_protect_only = 0;
2797     OUTER: for my $key (@keys) {
2798       my @cps = @{$buckets{$key}};
2799
2800       $logger->info("looking at " . scalar(@{$buckets{$key}}). " copies in proximity bucket $key");
2801
2802       for my $copyid (@cps) {
2803
2804          next if $seen{$copyid};
2805          $seen{$copyid} = 1; # there could be dupes given the merged buckets
2806          my $copy = $e->retrieve_asset_copy($copyid);
2807          $logger->debug("looking at bucket_key=$key, copy $copyid : circ_lib = " . $copy->circ_lib);
2808
2809          unless($title) { # grab the title if we don't already have it
2810             my $vol = $e->retrieve_asset_call_number(
2811                [ $copy->call_number, { flesh => 1, flesh_fields => { bre => ['fixed_fields'], acn => ['record'] } } ] );
2812             $title = $vol->record;
2813          }
2814
2815          @status = verify_copy_for_hold(
2816             $patron, $requestor, $title, $copy, $pickup_lib, $request_lib, $oargs);
2817
2818          $age_protect_only ||= $status[3];
2819          last OUTER if $status[0];
2820       }
2821     }
2822
2823     if (!$status[0]) {
2824         if (!defined($empty_ok)) {
2825             $empty_ok = $e->retrieve_config_global_flag('circ.holds.empty_issuance_ok');
2826             $empty_ok = ($empty_ok and $U->is_true($empty_ok->enabled));
2827         }
2828
2829         return (1,0) if ($empty_ok);
2830     }
2831     $status[3] = $age_protect_only;
2832     return @status;
2833 }
2834
2835 sub _check_monopart_hold_is_possible {
2836     my( $partid, $depth, $request_lib, $patron, $requestor, $pickup_lib, $selection_ou, $oargs ) = @_;
2837
2838     my $e = new_editor();
2839     my %org_filter = create_ranged_org_filter($e, $selection_ou, $depth);
2840
2841     # this monster will grab the id and circ_lib of all of the "holdable" copies for the given record
2842     my $copies = $e->json_query(
2843         {
2844             select => { acp => ['id', 'circ_lib'] },
2845               from => {
2846                 acp => {
2847                     acpm => {
2848                         field  => 'target_copy',
2849                         fkey   => 'id',
2850                         filter => { part => $partid }
2851                     },
2852                     acpl => {
2853                         field => 'id',
2854                         filter => { holdable => 't', deleted => 'f' },
2855                         fkey => 'location'
2856                     },
2857                     ccs  => { field => 'id', filter => { holdable => 't'}, fkey => 'status'   }
2858                 }
2859             },
2860             where => {
2861                 '+acp' => { circulate => 't', deleted => 'f', holdable => 't', %org_filter }
2862             },
2863             distinct => 1
2864         }
2865     );
2866
2867     $logger->info("monopart possible found ".scalar(@$copies)." potential copies");
2868
2869     my $empty_ok;
2870     if (!@$copies) {
2871         $empty_ok = $e->retrieve_config_global_flag('circ.holds.empty_part_ok');
2872         $empty_ok = ($empty_ok and $U->is_true($empty_ok->enabled));
2873
2874         return (
2875             0, 0, [
2876                 new OpenILS::Event(
2877                     "HIGH_LEVEL_HOLD_HAS_NO_COPIES",
2878                     "payload" => {"fail_part" => "no_ultimate_items"}
2879                 )
2880             ]
2881         ) unless $empty_ok;
2882
2883         return (1, 0);
2884     }
2885
2886     # -----------------------------------------------------------------------
2887     # sort the copies into buckets based on their circ_lib proximity to
2888     # the patron's home_ou.
2889     # -----------------------------------------------------------------------
2890
2891     my $home_org = $patron->home_ou;
2892     my $req_org = $request_lib->id;
2893
2894     $logger->info("prox cache $home_org " . $prox_cache{$home_org});
2895
2896     $prox_cache{$home_org} =
2897         $e->search_actor_org_unit_proximity({from_org => $home_org})
2898         unless $prox_cache{$home_org};
2899     my $home_prox = $prox_cache{$home_org};
2900
2901     my %buckets;
2902     my %hash = map { ($_->to_org => $_->prox) } @$home_prox;
2903     push( @{$buckets{ $hash{$_->{circ_lib}} } }, $_->{id} ) for @$copies;
2904
2905     my @keys = sort { $a <=> $b } keys %buckets;
2906
2907
2908     if( $home_org ne $req_org ) {
2909       # -----------------------------------------------------------------------
2910       # shove the copies close to the request_lib into the primary buckets
2911       # directly before the farthest away copies.  That way, they are not
2912       # given priority, but they are checked before the farthest copies.
2913       # -----------------------------------------------------------------------
2914         $prox_cache{$req_org} =
2915             $e->search_actor_org_unit_proximity({from_org => $req_org})
2916             unless $prox_cache{$req_org};
2917         my $req_prox = $prox_cache{$req_org};
2918
2919         my %buckets2;
2920         my %hash2 = map { ($_->to_org => $_->prox) } @$req_prox;
2921         push( @{$buckets2{ $hash2{$_->{circ_lib}} } }, $_->{id} ) for @$copies;
2922
2923         my $highest_key = $keys[@keys - 1];  # the farthest prox in the exising buckets
2924         my $new_key = $highest_key - 0.5; # right before the farthest prox
2925         my @keys2   = sort { $a <=> $b } keys %buckets2;
2926         for my $key (@keys2) {
2927             last if $key >= $highest_key;
2928             push( @{$buckets{$new_key}}, $_ ) for @{$buckets2{$key}};
2929         }
2930     }
2931
2932     @keys = sort { $a <=> $b } keys %buckets;
2933
2934     my $title;
2935     my %seen;
2936     my @status;
2937     my $age_protect_only = 0;
2938     OUTER: for my $key (@keys) {
2939       my @cps = @{$buckets{$key}};
2940
2941       $logger->info("looking at " . scalar(@{$buckets{$key}}). " copies in proximity bucket $key");
2942
2943       for my $copyid (@cps) {
2944
2945          next if $seen{$copyid};
2946          $seen{$copyid} = 1; # there could be dupes given the merged buckets
2947          my $copy = $e->retrieve_asset_copy($copyid);
2948          $logger->debug("looking at bucket_key=$key, copy $copyid : circ_lib = " . $copy->circ_lib);
2949
2950          unless($title) { # grab the title if we don't already have it
2951             my $vol = $e->retrieve_asset_call_number(
2952                [ $copy->call_number, { flesh => 1, flesh_fields => { bre => ['fixed_fields'], acn => ['record'] } } ] );
2953             $title = $vol->record;
2954          }
2955
2956          @status = verify_copy_for_hold(
2957             $patron, $requestor, $title, $copy, $pickup_lib, $request_lib, $oargs);
2958
2959          $age_protect_only ||= $status[3];
2960          last OUTER if $status[0];
2961       }
2962     }
2963
2964     if (!$status[0]) {
2965         if (!defined($empty_ok)) {
2966             $empty_ok = $e->retrieve_config_global_flag('circ.holds.empty_part_ok');
2967             $empty_ok = ($empty_ok and $U->is_true($empty_ok->enabled));
2968         }
2969
2970         return (1,0) if ($empty_ok);
2971     }
2972     $status[3] = $age_protect_only;
2973     return @status;
2974 }
2975
2976
2977 sub _check_volume_hold_is_possible {
2978     my( $vol, $title, $depth, $request_lib, $patron, $requestor, $pickup_lib, $selection_ou, $oargs ) = @_;
2979     my %org_filter = create_ranged_org_filter(new_editor(), $selection_ou, $depth);
2980     my $copies = new_editor->search_asset_copy({call_number => $vol->id, %org_filter});
2981     $logger->info("checking possibility of volume hold for volume ".$vol->id);
2982
2983     my $filter_copies = [];
2984     for my $copy (@$copies) {
2985         # ignore part-mapped copies for regular volume level holds
2986         push(@$filter_copies, $copy) unless
2987             new_editor->search_asset_copy_part_map({target_copy => $copy->id})->[0];
2988     }
2989     $copies = $filter_copies;
2990
2991     return (
2992         0, 0, [
2993             new OpenILS::Event(
2994                 "HIGH_LEVEL_HOLD_HAS_NO_COPIES",
2995                 "payload" => {"fail_part" => "no_ultimate_items"}
2996             )
2997         ]
2998     ) unless @$copies;
2999
3000     my @status;
3001     my $age_protect_only = 0;
3002     for my $copy ( @$copies ) {
3003         @status = verify_copy_for_hold(
3004             $patron, $requestor, $title, $copy, $pickup_lib, $request_lib, $oargs );
3005         $age_protect_only ||= $status[3];
3006         last if $status[0];
3007     }
3008     $status[3] = $age_protect_only;
3009     return @status;
3010 }
3011
3012
3013
3014 sub verify_copy_for_hold {
3015     my( $patron, $requestor, $title, $copy, $pickup_lib, $request_lib, $oargs ) = @_;
3016     # $oargs should be undef unless we're overriding.
3017     $logger->info("checking possibility of copy in hold request for copy ".$copy->id);
3018     my $permitted = OpenILS::Utils::PermitHold::permit_copy_hold(
3019         {
3020             patron           => $patron,
3021             requestor        => $requestor,
3022             copy             => $copy,
3023             title            => $title,
3024             title_descriptor => $title->fixed_fields,
3025             pickup_lib       => $pickup_lib,
3026             request_lib      => $request_lib,
3027             new_hold         => 1,
3028             show_event_list  => 1
3029         }
3030     );
3031
3032     # Check for override permissions on events.
3033     if ($oargs && $permitted && scalar @$permitted) {
3034         # Remove the events from permitted that we can override.
3035         if ($oargs->{events}) {
3036             foreach my $evt (@{$oargs->{events}}) {
3037                 $permitted = [grep {$_->{textcode} ne $evt} @{$permitted}];
3038             }
3039         }
3040         # Now, we handle the override all case by checking remaining
3041         # events against override permissions.
3042         if (scalar @$permitted && $oargs->{all}) {
3043             # Pre-set events and failed members of oargs to empty
3044             # arrays, if they are not set, yet.
3045             $oargs->{events} = [] unless ($oargs->{events});
3046             $oargs->{failed} = [] unless ($oargs->{failed});
3047             # When we're done with these checks, we swap permitted
3048             # with a reference to @disallowed.
3049             my @disallowed = ();
3050             foreach my $evt (@{$permitted}) {
3051                 # Check if we've already seen the event in this
3052                 # session and it failed.
3053                 if (grep {$_ eq $evt->{textcode}} @{$oargs->{failed}}) {
3054                     push(@disallowed, $evt);
3055                 } else {
3056                     # We have to check if the requestor has the
3057                     # override permission.
3058
3059                     # AppUtils::check_user_perms returns the perm if
3060                     # the user doesn't have it, undef if they do.
3061                     if ($apputils->check_user_perms($requestor->id, $requestor->ws_ou, $evt->{textcode} . '.override')) {
3062                         push(@disallowed, $evt);
3063                         push(@{$oargs->{failed}}, $evt->{textcode});
3064                     } else {
3065                         push(@{$oargs->{events}}, $evt->{textcode});
3066                     }
3067                 }
3068             }
3069             $permitted = \@disallowed;
3070         }
3071     }
3072
3073     my $age_protect_only = 0;
3074     if (@$permitted == 1 && @$permitted[0]->{textcode} eq 'ITEM_AGE_PROTECTED') {
3075         $age_protect_only = 1;
3076     }
3077
3078     return (
3079         (not scalar @$permitted), # true if permitted is an empty arrayref
3080         (   # XXX This test is of very dubious value; someone should figure
3081             # out what if anything is checking this value
3082             ($copy->circ_lib == $pickup_lib) and
3083             ($copy->status == OILS_COPY_STATUS_AVAILABLE)
3084         ),
3085         $permitted,
3086         $age_protect_only
3087     );
3088 }
3089
3090
3091
3092 sub find_nearest_permitted_hold {
3093
3094     my $class  = shift;
3095     my $editor = shift;     # CStoreEditor object
3096     my $copy   = shift;     # copy to target
3097     my $user   = shift;     # staff
3098     my $check_only = shift; # do no updates, just see if the copy could fulfill a hold
3099
3100     my $evt = OpenILS::Event->new('ACTION_HOLD_REQUEST_NOT_FOUND');
3101
3102     my $bc = $copy->barcode;
3103
3104     # find any existing holds that already target this copy
3105     my $old_holds = $editor->search_action_hold_request(
3106         {    current_copy => $copy->id,
3107             cancel_time  => undef,
3108             capture_time => undef
3109         }
3110     );
3111
3112     my $hold_stall_interval = $U->ou_ancestor_setting_value($user->ws_ou, OILS_SETTING_HOLD_SOFT_STALL);
3113
3114     $logger->info("circulator: searching for best hold at org ".$user->ws_ou.
3115         " and copy $bc with a hold stalling interval of ". ($hold_stall_interval || "(none)"));
3116
3117     my $fifo = $U->ou_ancestor_setting_value($user->ws_ou, 'circ.holds_fifo');
3118
3119     # the nearest_hold API call now needs this
3120     $copy->call_number($editor->retrieve_asset_call_number($copy->call_number))
3121         unless ref $copy->call_number;
3122
3123     # search for what should be the best holds for this copy to fulfill
3124     my $best_holds = $U->storagereq(
3125         "open-ils.storage.action.hold_request.nearest_hold.atomic",
3126         $user->ws_ou, $copy, 100, $hold_stall_interval, $fifo );
3127
3128     # Add any pre-targeted holds to the list too? Unless they are already there, anyway.
3129     if ($old_holds) {
3130         for my $holdid (@$old_holds) {
3131             next unless $holdid;
3132             push(@$best_holds, $holdid) unless ( grep { ''.$holdid eq ''.$_ } @$best_holds );
3133         }
3134     }
3135
3136     unless(@$best_holds) {
3137         $logger->info("circulator: no suitable holds found for copy $bc");
3138         return (undef, $evt);
3139     }
3140
3141
3142     my $best_hold;
3143
3144     # for each potential hold, we have to run the permit script
3145     # to make sure the hold is actually permitted.
3146     my %reqr_cache;
3147     my %org_cache;
3148     for my $holdid (@$best_holds) {
3149         next unless $holdid;
3150         $logger->info("circulator: checking if hold $holdid is permitted for copy $bc");
3151
3152         my $hold = $editor->retrieve_action_hold_request($holdid) or next;
3153         # Force and recall holds bypass all rules
3154         if ($hold->hold_type eq 'R' || $hold->hold_type eq 'F') {
3155             $best_hold = $hold;
3156             last;
3157         }
3158         my $reqr = $reqr_cache{$hold->requestor} || $editor->retrieve_actor_user($hold->requestor);
3159         my $rlib = $org_cache{$hold->request_lib} || $editor->retrieve_actor_org_unit($hold->request_lib);
3160
3161         $reqr_cache{$hold->requestor} = $reqr;
3162         $org_cache{$hold->request_lib} = $rlib;
3163
3164         # see if this hold is permitted
3165         my $permitted = OpenILS::Utils::PermitHold::permit_copy_hold(
3166             {
3167                 patron_id   => $hold->usr,
3168                 requestor   => $reqr,
3169                 copy        => $copy,
3170                 pickup_lib  => $hold->pickup_lib,
3171                 request_lib => $rlib,
3172                 retarget    => 1
3173             }
3174         );
3175
3176         if( $permitted ) {
3177             $best_hold = $hold;
3178             last;
3179         }
3180     }
3181
3182
3183     unless( $best_hold ) { # no "good" permitted holds were found
3184         # we got nuthin
3185         $logger->info("circulator: no suitable holds found for copy $bc");
3186         return (undef, $evt);
3187     }
3188
3189     $logger->info("circulator: best hold ".$best_hold->id." found for copy $bc");
3190
3191     # indicate a permitted hold was found
3192     return $best_hold if $check_only;
3193
3194     # we've found a permitted hold.  we need to "grab" the copy
3195     # to prevent re-targeted holds (next part) from re-grabbing the copy
3196     $best_hold->current_copy($copy->id);
3197     $editor->update_action_hold_request($best_hold)
3198         or return (undef, $editor->event);
3199
3200
3201     my @retarget;
3202
3203     # re-target any other holds that already target this copy
3204     for my $old_hold (@$old_holds) {
3205         next if $old_hold->id eq $best_hold->id; # don't re-target the hold we want
3206         $logger->info("circulator: clearing current_copy and prev_check_time on hold ".
3207             $old_hold->id." after a better hold [".$best_hold->id."] was found");
3208         $old_hold->clear_current_copy;
3209         $old_hold->clear_prev_check_time;
3210         $editor->update_action_hold_request($old_hold)
3211             or return (undef, $editor->event);
3212         push(@retarget, $old_hold->id);
3213     }
3214
3215     return ($best_hold, undef, (@retarget) ? \@retarget : undef);
3216 }
3217
3218
3219
3220
3221
3222
3223 __PACKAGE__->register_method(
3224     method   => 'all_rec_holds',
3225     api_name => 'open-ils.circ.holds.retrieve_all_from_title',
3226 );
3227
3228 sub all_rec_holds {
3229     my( $self, $conn, $auth, $title_id, $args ) = @_;
3230
3231     my $e = new_editor(authtoken=>$auth);
3232     $e->checkauth or return $e->event;
3233     $e->allowed('VIEW_HOLD') or return $e->event;
3234
3235     $args ||= {};
3236     $args->{fulfillment_time} = undef; #  we don't want to see old fulfilled holds
3237     $args->{cancel_time} = undef;
3238
3239     my $resp = {
3240           metarecord_holds => []
3241         , title_holds      => []
3242         , volume_holds     => []
3243         , copy_holds       => []
3244         , recall_holds     => []
3245         , force_holds      => []
3246         , part_holds       => []
3247         , issuance_holds   => []
3248     };
3249
3250     my $mr_map = $e->search_metabib_metarecord_source_map({source => $title_id})->[0];
3251     if($mr_map) {
3252         $resp->{metarecord_holds} = $e->search_action_hold_request(
3253             {   hold_type => OILS_HOLD_TYPE_METARECORD,
3254                 target => $mr_map->metarecord,
3255                 %$args
3256             }, {idlist => 1}
3257         );
3258     }
3259
3260     $resp->{title_holds} = $e->search_action_hold_request(
3261         {
3262             hold_type => OILS_HOLD_TYPE_TITLE,
3263             target => $title_id,
3264             %$args
3265         }, {idlist=>1} );
3266
3267     my $parts = $e->search_biblio_monograph_part(
3268         {
3269             record => $title_id
3270         }, {idlist=>1} );
3271
3272     if (@$parts) {
3273         $resp->{part_holds} = $e->search_action_hold_request(
3274             {
3275                 hold_type => OILS_HOLD_TYPE_MONOPART,
3276                 target => $parts,
3277                 %$args
3278             }, {idlist=>1} );
3279     }
3280
3281     my $subs = $e->search_serial_subscription(
3282         { record_entry => $title_id }, {idlist=>1});
3283
3284     if (@$subs) {
3285         my $issuances = $e->search_serial_issuance(
3286             {subscription => $subs}, {idlist=>1}
3287         );
3288
3289         if (@$issuances) {
3290             $resp->{issuance_holds} = $e->search_action_hold_request(
3291                 {
3292                     hold_type => OILS_HOLD_TYPE_ISSUANCE,
3293                     target => $issuances,
3294                     %$args
3295                 }, {idlist=>1}
3296             );
3297         }
3298     }
3299
3300     my $vols = $e->search_asset_call_number(
3301         { record => $title_id, deleted => 'f' }, {idlist=>1});
3302
3303     return $resp unless @$vols;
3304
3305     $resp->{volume_holds} = $e->search_action_hold_request(
3306         {
3307             hold_type => OILS_HOLD_TYPE_VOLUME,
3308             target => $vols,
3309             %$args },
3310         {idlist=>1} );
3311
3312     my $copies = $e->search_asset_copy(
3313         { call_number => $vols, deleted => 'f' }, {idlist=>1});
3314
3315     return $resp unless @$copies;
3316
3317     $resp->{copy_holds} = $e->search_action_hold_request(
3318         {
3319             hold_type => OILS_HOLD_TYPE_COPY,
3320             target => $copies,
3321             %$args },
3322         {idlist=>1} );
3323
3324     $resp->{recall_holds} = $e->search_action_hold_request(
3325         {
3326             hold_type => OILS_HOLD_TYPE_RECALL,
3327             target => $copies,
3328             %$args },
3329         {idlist=>1} );
3330
3331     $resp->{force_holds} = $e->search_action_hold_request(
3332         {
3333             hold_type => OILS_HOLD_TYPE_FORCE,
3334             target => $copies,
3335             %$args },
3336         {idlist=>1} );
3337
3338     return $resp;
3339 }
3340
3341
3342
3343
3344
3345 __PACKAGE__->register_method(
3346     method        => 'uber_hold',
3347     authoritative => 1,
3348     api_name      => 'open-ils.circ.hold.details.retrieve'
3349 );
3350
3351 sub uber_hold {
3352     my($self, $client, $auth, $hold_id, $args) = @_;
3353     my $e = new_editor(authtoken=>$auth);
3354     $e->checkauth or return $e->event;
3355     return uber_hold_impl($e, $hold_id, $args);
3356 }
3357
3358 __PACKAGE__->register_method(
3359     method        => 'batch_uber_hold',
3360     authoritative => 1,
3361     stream        => 1,
3362     api_name      => 'open-ils.circ.hold.details.batch.retrieve'
3363 );
3364
3365 sub batch_uber_hold {
3366     my($self, $client, $auth, $hold_ids, $args) = @_;
3367     my $e = new_editor(authtoken=>$auth);
3368     $e->checkauth or return $e->event;
3369     $client->respond(uber_hold_impl($e, $_, $args)) for @$hold_ids;
3370     return undef;
3371 }
3372
3373 sub uber_hold_impl {
3374     my($e, $hold_id, $args) = @_;
3375     $args ||= {};
3376
3377     my $hold = $e->retrieve_action_hold_request(
3378         [
3379             $hold_id,
3380             {
3381                 flesh => 1,
3382                 flesh_fields => { ahr => [ 'current_copy', 'usr', 'notes' ] }
3383             }
3384         ]
3385     ) or return $e->event;
3386
3387     if($hold->usr->id ne $e->requestor->id) {
3388         # caller is asking for someone else's hold
3389         $e->allowed('VIEW_HOLD') or return $e->event;
3390         $hold->notes( # filter out any non-staff ("private") notes (unless marked as public)
3391             [ grep { $U->is_true($_->staff) or $U->is_true($_->pub) } @{$hold->notes} ] );
3392
3393     } else {
3394         # caller is asking for own hold, but may not have permission to view staff notes
3395         unless($e->allowed('VIEW_HOLD')) {
3396             $hold->notes( # filter out any staff notes (unless marked as public)
3397                 [ grep { !$U->is_true($_->staff) or $U->is_true($_->pub) } @{$hold->notes} ] );
3398         }
3399     }
3400
3401     my $user = $hold->usr;
3402     $hold->usr($user->id);
3403
3404
3405     my( $mvr, $volume, $copy, $issuance, $part, $bre ) = find_hold_mvr($e, $hold, $args->{suppress_mvr});
3406
3407     flesh_hold_notices([$hold], $e) unless $args->{suppress_notices};
3408     flesh_hold_transits([$hold]) unless $args->{suppress_transits};
3409
3410     my $details = retrieve_hold_queue_status_impl($e, $hold);
3411
3412     my $resp = {
3413         hold    => $hold,
3414         bre_id  => $bre->id,
3415         ($copy     ? (copy           => $copy)     : ()),
3416         ($volume   ? (volume         => $volume)   : ()),
3417         ($issuance ? (issuance       => $issuance) : ()),
3418         ($part     ? (part           => $part)     : ()),
3419         ($args->{include_bre}  ?  (bre => $bre)    : ()),
3420         ($args->{suppress_mvr} ?  () : (mvr => $mvr)),
3421         %$details
3422     };
3423
3424     $resp->{copy}->location(
3425         $e->retrieve_asset_copy_location($resp->{copy}->location))
3426         if $resp->{copy} and $args->{flesh_acpl};
3427
3428     unless($args->{suppress_patron_details}) {
3429         my $card = $e->retrieve_actor_card($user->card) or return $e->event;
3430         $resp->{patron_first}   = $user->first_given_name,
3431         $resp->{patron_last}    = $user->family_name,
3432         $resp->{patron_barcode} = $card->barcode,
3433         $resp->{patron_alias}   = $user->alias,
3434     };
3435
3436     return $resp;
3437 }
3438
3439
3440
3441 # -----------------------------------------------------
3442 # Returns the MVR object that represents what the
3443 # hold is all about
3444 # -----------------------------------------------------
3445 sub find_hold_mvr {
3446     my( $e, $hold, $no_mvr ) = @_;
3447
3448     my $tid;
3449     my $copy;
3450     my $volume;
3451     my $issuance;
3452     my $part;
3453
3454     if( $hold->hold_type eq OILS_HOLD_TYPE_METARECORD ) {
3455         my $mr = $e->retrieve_metabib_metarecord($hold->target)
3456             or return $e->event;
3457         $tid = $mr->master_record;
3458
3459     } elsif( $hold->hold_type eq OILS_HOLD_TYPE_TITLE ) {
3460         $tid = $hold->target;
3461
3462     } elsif( $hold->hold_type eq OILS_HOLD_TYPE_VOLUME ) {
3463         $volume = $e->retrieve_asset_call_number($hold->target)
3464             or return $e->event;
3465         $tid = $volume->record;
3466
3467     } elsif( $hold->hold_type eq OILS_HOLD_TYPE_ISSUANCE ) {
3468         $issuance = $e->retrieve_serial_issuance([
3469             $hold->target,
3470             {flesh => 1, flesh_fields => {siss => [ qw/subscription/ ]}}
3471         ]) or return $e->event;
3472
3473         $tid = $issuance->subscription->record_entry;
3474
3475     } elsif( $hold->hold_type eq OILS_HOLD_TYPE_MONOPART ) {
3476         $part = $e->retrieve_biblio_monograph_part([
3477             $hold->target
3478         ]) or return $e->event;
3479
3480         $tid = $part->record;
3481
3482     } elsif( $hold->hold_type eq OILS_HOLD_TYPE_COPY || $hold->hold_type eq OILS_HOLD_TYPE_RECALL || $hold->hold_type eq OILS_HOLD_TYPE_FORCE ) {
3483         $copy = $e->retrieve_asset_copy([
3484             $hold->target,
3485             {flesh => 1, flesh_fields => {acp => ['call_number']}}
3486         ]) or return $e->event;
3487
3488         $volume = $copy->call_number;
3489         $tid = $volume->record;
3490     }
3491
3492     if(!$copy and ref $hold->current_copy ) {
3493         $copy = $hold->current_copy;
3494         $hold->current_copy($copy->id);
3495     }
3496
3497     if(!$volume and $copy) {
3498         $volume = $e->retrieve_asset_call_number($copy->call_number);
3499     }
3500
3501     # TODO return metarcord mvr for M holds
3502     my $title = $e->retrieve_biblio_record_entry($tid);
3503     return ( ($no_mvr) ? undef : $U->record_to_mvr($title), $volume, $copy, $issuance, $part, $title );
3504 }
3505
3506 __PACKAGE__->register_method(
3507     method    => 'clear_shelf_cache',
3508     api_name  => 'open-ils.circ.hold.clear_shelf.get_cache',
3509     stream    => 1,
3510     signature => {
3511         desc => q/
3512             Returns the holds processed with the given cache key
3513         /
3514     }
3515 );
3516
3517 sub clear_shelf_cache {
3518     my($self, $client, $auth, $cache_key, $chunk_size) = @_;
3519     my $e = new_editor(authtoken => $auth, xact => 1);
3520     return $e->die_event unless $e->checkauth and $e->allowed('VIEW_HOLD');
3521
3522     $chunk_size ||= 25;
3523     $client->max_chunk_size($chunk_size) if ($client->can('max_chunk_size'));
3524
3525     my $hold_data = OpenSRF::Utils::Cache->new('global')->get_cache($cache_key);
3526
3527     if (!$hold_data) {
3528         $logger->info("no hold data found in cache"); # XXX TODO return event
3529         $e->rollback;
3530         return undef;
3531     }
3532
3533     my $maximum = 0;
3534     foreach (keys %$hold_data) {
3535         $maximum += scalar(@{ $hold_data->{$_} });
3536     }
3537     $client->respond({"maximum" => $maximum, "progress" => 0});
3538
3539     for my $action (sort keys %$hold_data) {
3540         while (@{$hold_data->{$action}}) {
3541             my @hid_chunk = splice @{$hold_data->{$action}}, 0, $chunk_size;
3542
3543             my $result_chunk = $e->json_query({
3544                 "select" => {
3545                     "acp" => ["barcode"],
3546                     "au" => [qw/
3547                         first_given_name second_given_name family_name alias
3548                     /],
3549                     "acn" => ["label"],
3550                     "acnp" => [{column => "label", alias => "prefix"}],
3551                     "acns" => [{column => "label", alias => "suffix"}],
3552                     "bre" => ["marc"],
3553                     "acpl" => ["name"],
3554                     "ahr" => ["id"]
3555                 },
3556                 "from" => {
3557                     "ahr" => {
3558                         "acp" => {
3559                             "field" => "id", "fkey" => "current_copy",
3560                             "join" => {
3561                                 "acn" => {
3562                                     "field" => "id", "fkey" => "call_number",
3563                                     "join" => {
3564                                         "bre" => {
3565                                             "field" => "id", "fkey" => "record"
3566                                         },
3567                                         "acnp" => {
3568                                             "field" => "id", "fkey" => "prefix"
3569                                         },
3570                                         "acns" => {
3571                                             "field" => "id", "fkey" => "suffix"
3572                                         }
3573                                     }
3574                                 },
3575                                 "acpl" => {"field" => "id", "fkey" => "location"}
3576                             }
3577                         },
3578                         "au" => {"field" => "id", "fkey" => "usr"}
3579                     }
3580                 },
3581                 "where" => {"+ahr" => {"id" => \@hid_chunk}}
3582             }, {"substream" => 1}) or return $e->die_event;
3583
3584             $client->respond([
3585                 map {
3586                     +{"action" => $action, "hold_details" => $_}
3587                 } @$result_chunk
3588             ]);
3589         }
3590     }
3591
3592     $e->rollback;
3593     return undef;
3594 }
3595
3596
3597 __PACKAGE__->register_method(
3598     method    => 'clear_shelf_process',
3599     stream    => 1,
3600     api_name  => 'open-ils.circ.hold.clear_shelf.process',
3601     signature => {
3602         desc => q/
3603             1. Find all holds that have expired on the holds shelf
3604             2. Cancel the holds
3605             3. If a clear-shelf status is configured, put targeted copies into this status
3606             4. Divide copies into 3 groups: items to transit, items to reshelve, and items
3607                 that are needed for holds.  No subsequent action is taken on the holds
3608                 or items after grouping.
3609         /
3610     }
3611 );
3612
3613 sub clear_shelf_process {
3614     my($self, $client, $auth, $org_id, $match_copy, $chunk_size) = @_;
3615
3616     my $e = new_editor(authtoken=>$auth);
3617     $e->checkauth or return $e->die_event;
3618     my $cache = OpenSRF::Utils::Cache->new('global');
3619
3620     $org_id ||= $e->requestor->ws_ou;
3621     $e->allowed('UPDATE_HOLD', $org_id) or return $e->die_event;
3622
3623     my $copy_status = $U->ou_ancestor_setting_value($org_id, 'circ.holds.clear_shelf.copy_status');
3624
3625     my @hold_ids = $self->method_lookup(
3626         "open-ils.circ.captured_holds.id_list.expired_on_shelf.retrieve"
3627     )->run($auth, $org_id, $match_copy);
3628
3629     $e->xact_begin;
3630
3631     my @holds;
3632     my @canceled_holds; # newly canceled holds
3633     $chunk_size ||= 25; # chunked status updates
3634     $client->max_chunk_size($chunk_size) if ($client->can('max_chunk_size'));
3635
3636     my $counter = 0;
3637     for my $hold_id (@hold_ids) {
3638
3639         $logger->info("Clear shelf processing hold $hold_id");
3640
3641         my $hold = $e->retrieve_action_hold_request([
3642             $hold_id, {
3643                 flesh => 1,
3644                 flesh_fields => {ahr => ['current_copy']}
3645             }
3646         ]);
3647
3648         if (!$hold->cancel_time) { # may be canceled but still on the holds shelf
3649             $hold->cancel_time('now');
3650             $hold->cancel_cause(2); # Hold Shelf expiration
3651             $e->update_action_hold_request($hold) or return $e->die_event;
3652             push(@canceled_holds, $hold_id);
3653         }
3654
3655         my $copy = $hold->current_copy;
3656
3657         if($copy_status or $copy_status == 0) {
3658             # if a clear-shelf copy status is defined, update the copy
3659             $copy->status($copy_status);
3660             $copy->edit_date('now');
3661             $copy->editor($e->requestor->id);
3662             $e->update_asset_copy($copy) or return $e->die_event;
3663         }
3664
3665         push(@holds, $hold);
3666         $client->respond({maximum => scalar(@holds), progress => $counter}) if ( (++$counter % $chunk_size) == 0);
3667     }
3668
3669     if ($e->commit) {
3670
3671         my %cache_data = (
3672             hold => [],
3673             transit => [],
3674             shelf => [],
3675             pl_changed => pickup_lib_changed_on_shelf_holds($e, $org_id, \@hold_ids)
3676         );
3677
3678         for my $hold (@holds) {
3679
3680             my $copy = $hold->current_copy;
3681             my ($alt_hold) = __PACKAGE__->find_nearest_permitted_hold($e, $copy, $e->requestor, 1);
3682
3683             if($alt_hold and !$match_copy) {
3684
3685                 push(@{$cache_data{hold}}, $hold->id); # copy is needed for a hold
3686
3687             } elsif($copy->circ_lib != $e->requestor->ws_ou) {
3688
3689                 push(@{$cache_data{transit}}, $hold->id); # copy needs to transit
3690
3691             } else {
3692
3693                 push(@{$cache_data{shelf}}, $hold->id); # copy needs to go back to the shelf
3694             }
3695         }
3696
3697         my $cache_key = md5_hex(time . $$ . rand());
3698         $logger->info("clear_shelf_cache: storing under $cache_key");
3699         $cache->put_cache($cache_key, \%cache_data, 7200); # TODO: 2 hours.  configurable?
3700
3701         # tell the client we're done
3702         $client->respond_complete({cache_key => $cache_key});
3703
3704         # ------------
3705         # fire off the hold cancelation trigger and wait for response so don't flood the service
3706
3707         # refetch the holds to pick up the caclulated cancel_time,
3708         # which may be needed by Action/Trigger
3709         $e->xact_begin;
3710         my $updated_holds = [];
3711         $updated_holds = $e->search_action_hold_request({id => \@canceled_holds}, {substream => 1}) if (@canceled_holds > 0);
3712         $e->rollback;
3713
3714         $U->create_events_for_hook(
3715             'hold_request.cancel.expire_holds_shelf',
3716             $_, $org_id, undef, undef, 1) for @$updated_holds;
3717
3718     } else {
3719         # tell the client we're done
3720         $client->respond_complete;
3721     }
3722 }
3723
3724 # returns IDs for holds that are on the holds shelf but
3725 # have had their pickup_libs change while on the shelf.
3726 sub pickup_lib_changed_on_shelf_holds {
3727     my $e = shift;
3728     my $org_id = shift;
3729     my $ignore_holds = shift;
3730     $ignore_holds = [$ignore_holds] if !ref($ignore_holds);
3731
3732     my $query = {
3733         select => { alhr => ['id'] },
3734         from   => {
3735             alhr => {
3736                 acp => {
3737                     field => 'id',
3738                     fkey  => 'current_copy'
3739                 },
3740             }
3741         },
3742         where => {
3743             '+acp' => { status => OILS_COPY_STATUS_ON_HOLDS_SHELF },
3744             '+alhr' => {
3745                 capture_time     => { "!=" => undef },
3746                 fulfillment_time => undef,
3747                 current_shelf_lib => $org_id,
3748                 pickup_lib => {'!='  => {'+alhr' => 'current_shelf_lib'}}
3749             }
3750         }
3751     };
3752
3753     $query->{where}->{'+alhr'}->{id} =
3754         {'not in' => $ignore_holds} if @$ignore_holds;
3755
3756     my $hold_ids = $e->json_query($query);
3757     return [ map { $_->{id} } @$hold_ids ];
3758 }
3759
3760 __PACKAGE__->register_method(
3761     method    => 'usr_hold_summary',
3762     api_name  => 'open-ils.circ.holds.user_summary',
3763     signature => q/
3764         Returns a summary of holds statuses for a given user
3765     /
3766 );
3767
3768 sub usr_hold_summary {
3769     my($self, $conn, $auth, $user_id) = @_;
3770
3771     my $e = new_editor(authtoken=>$auth);
3772     $e->checkauth or return $e->event;
3773     $e->allowed('VIEW_HOLD') or return $e->event;
3774
3775     my $holds = $e->search_action_hold_request(
3776         {
3777             usr =>  $user_id ,
3778             fulfillment_time => undef,
3779             cancel_time      => undef,
3780         }
3781     );
3782
3783     my %summary = (1 => 0, 2 => 0, 3 => 0, 4 => 0);
3784     $summary{_hold_status($e, $_)} += 1 for @$holds;
3785     return \%summary;
3786 }
3787
3788
3789
3790 __PACKAGE__->register_method(
3791     method    => 'hold_has_copy_at',
3792     api_name  => 'open-ils.circ.hold.has_copy_at',
3793     signature => {
3794         desc   =>
3795                 'Returns the ID of the found copy and name of the shelving location if there is ' .
3796                 'an available copy at the specified org unit.  Returns empty hash otherwise.  '   .
3797                 'The anticipated use for this method is to determine whether an item is '         .
3798                 'available at the library where the user is placing the hold (or, alternatively, '.
3799                 'at the pickup library) to encourage bypassing the hold placement and just '      .
3800                 'checking out the item.' ,
3801         params => [
3802             { desc => 'Authentication Token', type => 'string' },
3803             { desc => 'Method Arguments.  Options include: hold_type, hold_target, org_unit.  '
3804                     . 'hold_type is the hold type code (T, V, C, M, ...).  '
3805                     . 'hold_target is the identifier of the hold target object.  '
3806                     . 'org_unit is org unit ID.',
3807               type => 'object'
3808             }
3809         ],
3810         return => {
3811             desc => q/Result hash like { "copy" : copy_id, "location" : location_name }, empty hash on misses, event on error./,
3812             type => 'object'
3813         }
3814     }
3815 );
3816
3817 sub hold_has_copy_at {
3818     my($self, $conn, $auth, $args) = @_;
3819
3820     my $e = new_editor(authtoken=>$auth);
3821     $e->checkauth or return $e->event;
3822
3823     my $hold_type   = $$args{hold_type};
3824     my $hold_target = $$args{hold_target};
3825     my $org_unit    = $$args{org_unit};
3826
3827     my $query = {
3828         select => {acp => ['id'], acpl => ['name']},
3829         from   => {
3830             acp => {
3831                 acpl => {
3832                     field => 'id',
3833                     filter => { holdable => 't', deleted => 'f' },
3834                     fkey => 'location'
3835                 },
3836                 ccs  => {field => 'id', filter => { holdable => 't'}, fkey => 'status'  }
3837             }
3838         },
3839         where => {'+acp' => { circulate => 't', deleted => 'f', holdable => 't', circ_lib => $org_unit, status => [0,7]}},
3840         limit => 1
3841     };
3842
3843     if($hold_type eq 'C' or $hold_type eq 'F' or $hold_type eq 'R') {
3844
3845         $query->{where}->{'+acp'}->{id} = $hold_target;
3846
3847     } elsif($hold_type eq 'V') {
3848
3849         $query->{where}->{'+acp'}->{call_number} = $hold_target;
3850
3851     } elsif($hold_type eq 'P') {
3852
3853         $query->{from}->{acp}->{acpm} = {
3854             field  => 'target_copy',
3855             fkey   => 'id',
3856             filter => {part => $hold_target},
3857         };
3858
3859     } elsif($hold_type eq 'I') {
3860
3861         $query->{from}->{acp}->{sitem} = {
3862             field  => 'unit',
3863             fkey   => 'id',
3864             filter => {issuance => $hold_target},
3865         };
3866
3867     } elsif($hold_type eq 'T') {
3868
3869         $query->{from}->{acp}->{acn} = {
3870             field  => 'id',
3871             fkey   => 'call_number',
3872             'join' => {
3873                 bre => {
3874                     field  => 'id',
3875                     filter => {id => $hold_target},
3876                     fkey   => 'record'
3877                 }
3878             }
3879         };
3880
3881     } else {
3882
3883         $query->{from}->{acp}->{acn} = {
3884             field => 'id',
3885             fkey  => 'call_number',
3886             join  => {
3887                 bre => {
3888                     field => 'id',
3889                     fkey  => 'record',
3890                     join  => {
3891                         mmrsm => {
3892                             field  => 'source',
3893                             fkey   => 'id',
3894                             filter => {metarecord => $hold_target},
3895                         }
3896                     }
3897                 }
3898             }
3899         };
3900     }
3901
3902     my $res = $e->json_query($query)->[0] or return {};
3903     return {copy => $res->{id}, location => $res->{name}} if $res;
3904 }
3905
3906
3907 # returns true if the user already has an item checked out
3908 # that could be used to fulfill the requested hold.
3909 sub hold_item_is_checked_out {
3910     my($e, $user_id, $hold_type, $hold_target) = @_;
3911
3912     my $query = {
3913         select => {acp => ['id']},
3914         from   => {acp => {}},
3915         where  => {
3916             '+acp' => {
3917                 id => {
3918                     in => { # copies for circs the user has checked out
3919                         select => {circ => ['target_copy']},
3920                         from   => 'circ',
3921                         where  => {
3922                             usr => $user_id,
3923                             checkin_time => undef,
3924                             '-or' => [
3925                                 {stop_fines => ["MAXFINES","LONGOVERDUE"]},
3926                                 {stop_fines => undef}
3927                             ],
3928                         }
3929                     }
3930                 }
3931             }
3932         },
3933         limit => 1
3934     };
3935
3936     if($hold_type eq 'C' || $hold_type eq 'R' || $hold_type eq 'F') {
3937
3938         $query->{where}->{'+acp'}->{id}->{in}->{where}->{'target_copy'} = $hold_target;
3939
3940     } elsif($hold_type eq 'V') {
3941
3942         $query->{where}->{'+acp'}->{call_number} = $hold_target;
3943
3944      } elsif($hold_type eq 'P') {
3945
3946         $query->{from}->{acp}->{acpm} = {
3947             field  => 'target_copy',
3948             fkey   => 'id',
3949             filter => {part => $hold_target},
3950         };
3951
3952      } elsif($hold_type eq 'I') {
3953
3954         $query->{from}->{acp}->{sitem} = {
3955             field  => 'unit',
3956             fkey   => 'id',
3957             filter => {issuance => $hold_target},
3958         };
3959
3960     } elsif($hold_type eq 'T') {
3961
3962         $query->{from}->{acp}->{acn} = {
3963             field  => 'id',
3964             fkey   => 'call_number',
3965             'join' => {
3966                 bre => {
3967                     field  => 'id',
3968                     filter => {id => $hold_target},
3969                     fkey   => 'record'
3970                 }
3971             }
3972         };
3973
3974     } else {
3975
3976         $query->{from}->{acp}->{acn} = {
3977             field => 'id',
3978             fkey => 'call_number',
3979             join => {
3980                 bre => {
3981                     field => 'id',
3982                     fkey => 'record',
3983                     join => {
3984                         mmrsm => {
3985                             field => 'source',
3986                             fkey => 'id',
3987                             filter => {metarecord => $hold_target},
3988                         }
3989                     }
3990                 }
3991             }
3992         };
3993     }
3994
3995     return $e->json_query($query)->[0];
3996 }
3997
3998 __PACKAGE__->register_method(
3999     method    => 'change_hold_title',
4000     api_name  => 'open-ils.circ.hold.change_title',
4001     signature => {
4002         desc => q/
4003             Updates all title level holds targeting the specified bibs to point a new bib./,
4004         params => [
4005             { desc => 'Authentication Token', type => 'string' },
4006             { desc => 'New Target Bib Id',    type => 'number' },
4007             { desc => 'Old Target Bib Ids',   type => 'array'  },
4008         ],
4009         return => { desc => '1 on success' }
4010     }
4011 );
4012
4013 __PACKAGE__->register_method(
4014     method    => 'change_hold_title_for_specific_holds',
4015     api_name  => 'open-ils.circ.hold.change_title.specific_holds',
4016     signature => {
4017         desc => q/
4018             Updates specified holds to target new bib./,
4019         params => [
4020             { desc => 'Authentication Token', type => 'string' },
4021             { desc => 'New Target Bib Id',    type => 'number' },
4022             { desc => 'Holds Ids for holds to update',   type => 'array'  },
4023         ],
4024         return => { desc => '1 on success' }
4025     }
4026 );
4027
4028
4029 sub change_hold_title {
4030     my( $self, $client, $auth, $new_bib_id, $bib_ids ) = @_;
4031
4032     my $e = new_editor(authtoken=>$auth, xact=>1);
4033     return $e->die_event unless $e->checkauth;
4034
4035     my $holds = $e->search_action_hold_request(
4036         [
4037             {
4038                 cancel_time      => undef,
4039                 fulfillment_time => undef,
4040                 hold_type        => 'T',
4041                 target           => $bib_ids
4042             },
4043             {
4044                 flesh        => 1,
4045                 flesh_fields => { ahr => ['usr'] }
4046             }
4047         ],
4048         { substream => 1 }
4049     );
4050
4051     for my $hold (@$holds) {
4052         $e->allowed('UPDATE_HOLD', $hold->usr->home_ou) or return $e->die_event;
4053         $logger->info("Changing hold " . $hold->id . " target from " . $hold->target . " to $new_bib_id in title hold target change");
4054         $hold->target( $new_bib_id );
4055         $e->update_action_hold_request($hold) or return $e->die_event;
4056     }
4057
4058     $e->commit;
4059
4060     _reset_hold($self, $e->requestor, $_) for @$holds;
4061
4062     return 1;
4063 }
4064
4065 sub change_hold_title_for_specific_holds {
4066     my( $self, $client, $auth, $new_bib_id, $hold_ids ) = @_;
4067
4068     my $e = new_editor(authtoken=>$auth, xact=>1);
4069     return $e->die_event unless $e->checkauth;
4070
4071     my $holds = $e->search_action_hold_request(
4072         [
4073             {
4074                 cancel_time      => undef,
4075                 fulfillment_time => undef,
4076                 hold_type        => 'T',
4077                 id               => $hold_ids
4078             },
4079             {
4080                 flesh        => 1,
4081                 flesh_fields => { ahr => ['usr'] }
4082             }
4083         ],
4084         { substream => 1 }
4085     );
4086
4087     for my $hold (@$holds) {
4088         $e->allowed('UPDATE_HOLD', $hold->usr->home_ou) or return $e->die_event;
4089         $logger->info("Changing hold " . $hold->id . " target from " . $hold->target . " to $new_bib_id in title hold target change");
4090         $hold->target( $new_bib_id );
4091         $e->update_action_hold_request($hold) or return $e->die_event;
4092     }
4093
4094     $e->commit;
4095
4096     _reset_hold($self, $e->requestor, $_) for @$holds;
4097
4098     return 1;
4099 }
4100
4101 __PACKAGE__->register_method(
4102     method    => 'rec_hold_count',
4103     api_name  => 'open-ils.circ.bre.holds.count',
4104     signature => {
4105         desc => q/Returns the total number of holds that target the
4106             selected bib record or its associated copies and call_numbers/,
4107         params => [
4108             { desc => 'Bib ID', type => 'number' },
4109             { desc => q/Optional arguments.  Supported arguments include:
4110                 "pickup_lib_descendant" -> limit holds to those whose pickup
4111                 library is equal to or is a child of the provided org unit/,
4112                 type => 'object'
4113             }
4114         ],
4115         return => {desc => 'Hold count', type => 'number'}
4116     }
4117 );
4118
4119 __PACKAGE__->register_method(
4120     method    => 'rec_hold_count',
4121     api_name  => 'open-ils.circ.mmr.holds.count',
4122     signature => {
4123         desc => q/Returns the total number of holds that target the
4124             selected metarecord or its associated copies, call_numbers, and bib records/,
4125         params => [
4126             { desc => 'Metarecord ID', type => 'number' },
4127         ],
4128         return => {desc => 'Hold count', type => 'number'}
4129     }
4130 );
4131
4132 # XXX Need to add type I holds to these counts
4133 sub rec_hold_count {
4134     my($self, $conn, $target_id, $args) = @_;
4135     $args ||= {};
4136
4137     my $mmr_join = {
4138         mmrsm => {
4139             field => 'source',
4140             fkey => 'id',
4141             filter => {metarecord => $target_id}
4142         }
4143     };
4144
4145     my $bre_join = {
4146         bre => {
4147             field => 'id',
4148             filter => { id => $target_id },
4149             fkey => 'record'
4150         }
4151     };
4152
4153     if($self->api_name =~ /mmr/) {
4154         delete $bre_join->{bre}->{filter};
4155         $bre_join->{bre}->{join} = $mmr_join;
4156     }
4157
4158     my $cn_join = {
4159         acn => {
4160             field => 'id',
4161             fkey => 'call_number',
4162             join => $bre_join
4163         }
4164     };
4165
4166     my $query = {
4167         select => {ahr => [{column => 'id', transform => 'count', alias => 'count'}]},
4168         from => 'ahr',
4169         where => {
4170             '+ahr' => {
4171                 cancel_time => undef,
4172                 fulfillment_time => undef,
4173                 '-or' => [
4174                     {
4175                         '-and' => {
4176                             hold_type => [qw/C F R/],
4177                             target => {
4178                                 in => {
4179                                     select => {acp => ['id']},
4180                                     from => { acp => $cn_join }
4181                                 }
4182                             }
4183                         }
4184                     },
4185                     {
4186                         '-and' => {
4187                             hold_type => 'V',
4188                             target => {
4189                                 in => {
4190                                     select => {acn => ['id']},
4191                                     from => {acn => $bre_join}
4192                                 }
4193                             }
4194                         }
4195                     },
4196                     {
4197                         '-and' => {
4198                             hold_type => 'P',
4199                             target => {
4200                                 in => {
4201                                     select => {bmp => ['id']},
4202                                     from => {bmp => $bre_join}
4203                                 }
4204                             }
4205                         }
4206                     },
4207                     {
4208                         '-and' => {
4209                             hold_type => 'T',
4210                             target => $target_id
4211                         }
4212                     }
4213                 ]
4214             }
4215         }
4216     };
4217
4218     if($self->api_name =~ /mmr/) {
4219         $query->{where}->{'+ahr'}->{'-or'}->[3] = {
4220             '-and' => {
4221                 hold_type => 'T',
4222                 target => {
4223                     in => {
4224                         select => {bre => ['id']},
4225                         from => {bre => $mmr_join}
4226                     }
4227                 }
4228             }
4229         };
4230
4231         $query->{where}->{'+ahr'}->{'-or'}->[4] = {
4232             '-and' => {
4233                 hold_type => 'M',
4234                 target => $target_id
4235             }
4236         };
4237     }
4238
4239
4240     if (my $pld = $args->{pickup_lib_descendant}) {
4241
4242         my $top_ou = new_editor()->search_actor_org_unit(
4243             {parent_ou => undef}
4244         )->[0]; # XXX Assumes single root node. Not alone in this...
4245
4246         $query->{where}->{'+ahr'}->{pickup_lib} = {
4247             in => {
4248                 select  => {aou => [{
4249                     column => 'id',
4250                     transform => 'actor.org_unit_descendants',
4251                     result_field => 'id'
4252                 }]},
4253                 from    => 'aou',
4254                 where   => {id => $pld}
4255             }
4256         } if ($pld != $top_ou->id);
4257     }
4258
4259
4260     return new_editor()->json_query($query)->[0]->{count};
4261 }
4262
4263 # A helper function to calculate a hold's expiration time at a given
4264 # org_unit. Takes the org_unit as an argument and returns either the
4265 # hold expire time as an ISO8601 string or undef if there is no hold
4266 # expiration interval set for the subject ou.
4267 sub calculate_expire_time
4268 {
4269     my $ou = shift;
4270     my $interval = $U->ou_ancestor_setting_value($ou, OILS_SETTING_HOLD_EXPIRE);
4271     if($interval) {
4272         my $date = DateTime->now->add(seconds => OpenSRF::Utils::interval_to_seconds($interval));
4273         return $U->epoch2ISO8601($date->epoch);
4274     }
4275     return undef;
4276 }
4277
4278
4279 __PACKAGE__->register_method(
4280     method    => 'mr_hold_filter_attrs',
4281     api_name  => 'open-ils.circ.mmr.holds.filters',
4282     authoritative => 1,
4283     stream => 1,
4284     signature => {
4285         desc => q/
4286             Returns the set of available formats and languages for the
4287             constituent records of the provided metarcord.
4288             If an array of hold IDs is also provided, information about
4289             each is returned as well.  This information includes:
4290             1. a slightly easier to read version of holdable_formats
4291             2. attributes describing the set of format icons included
4292                in the set of desired, constituent records.
4293         /,
4294         params => [
4295             {desc => 'Metarecord ID', type => 'number'},
4296             {desc => 'Context Org ID', type => 'number'},
4297             {desc => 'Hold ID List', type => 'array'},
4298         ],
4299         return => {
4300             desc => q/
4301                 Stream of objects.  The first will have a 'metarecord' key
4302                 containing non-hold-specific metarecord information, subsequent
4303                 responses will contain a 'hold' key containing hold-specific
4304                 information
4305             /,
4306             type => 'object'
4307         }
4308     }
4309 );
4310
4311 sub mr_hold_filter_attrs {
4312     my ($self, $client, $mr_id, $org_id, $hold_ids) = @_;
4313     my $e = new_editor();
4314
4315     # by default, return MR / hold attributes for all constituent
4316     # records with holdable copies.  If there is a hard boundary,
4317     # though, limit to records with copies within the boundary,
4318     # since anything outside the boundary can never be held.
4319     my $org_depth = 0;
4320     if ($org_id) {
4321         $org_depth = $U->ou_ancestor_setting_value(
4322             $org_id, OILS_SETTING_HOLD_HARD_BOUNDARY) || 0;
4323     }
4324
4325     # get all org-scoped records w/ holdable copies for this metarecord
4326     my ($bre_ids) = $self->method_lookup(
4327         'open-ils.circ.holds.metarecord.filtered_records')->run(
4328             $mr_id, undef, $org_id, $org_depth);
4329
4330     my $item_lang_attr = 'item_lang'; # configurable?
4331     my $format_attr = $e->retrieve_config_global_flag(
4332         'opac.metarecord.holds.format_attr')->value;
4333
4334     # helper sub for fetching ccvms for a batch of record IDs
4335     sub get_batch_ccvms {
4336         my ($e, $attr, $bre_ids) = @_;
4337         return [] unless $bre_ids and @$bre_ids;
4338         my $vals = $e->search_metabib_record_attr_flat({
4339             attr => $attr,
4340             id => $bre_ids
4341         });
4342         return [] unless @$vals;
4343         return $e->search_config_coded_value_map({
4344             ctype => $attr,
4345             code => [map {$_->value} @$vals]
4346         });
4347     }
4348
4349     my $langs = get_batch_ccvms($e, $item_lang_attr, $bre_ids);
4350     my $formats = get_batch_ccvms($e, $format_attr, $bre_ids);
4351
4352     $client->respond({
4353         metarecord => {
4354             id => $mr_id,
4355             formats => $formats,
4356             langs => $langs
4357         }
4358     });
4359
4360     return unless $hold_ids;
4361     my $icon_attr = $e->retrieve_config_global_flag('opac.icon_attr');
4362     $icon_attr = $icon_attr ? $icon_attr->value : '';
4363
4364     for my $hold_id (@$hold_ids) {
4365         my $hold = $e->retrieve_action_hold_request($hold_id)
4366             or return $e->event;
4367
4368         next unless $hold->hold_type eq 'M';
4369
4370         my $resp = {
4371             hold => {
4372                 id => $hold_id,
4373                 formats => [],
4374                 langs => []
4375             }
4376         };
4377
4378         # collect the ccvm's for the selected formats / language
4379         # (i.e. the holdable formats) on the MR.
4380         # this assumes a two-key structure for format / language,
4381         # though no assumption is made about the keys themselves.
4382         my $hformats = OpenSRF::Utils::JSON->JSON2perl($hold->holdable_formats);
4383         my $lang_vals = [];
4384         my $format_vals = [];
4385         for my $val (values %$hformats) {
4386             # val is either a single ccvm or an array of them
4387             $val = [$val] unless ref $val eq 'ARRAY';
4388             for my $node (@$val) {
4389                 push (@$lang_vals, $node->{_val})
4390                     if $node->{_attr} eq $item_lang_attr;
4391                 push (@$format_vals, $node->{_val})
4392                     if $node->{_attr} eq $format_attr;
4393             }
4394         }
4395
4396         # fetch the ccvm's for consistency with the {metarecord} blob
4397         $resp->{hold}{formats} = $e->search_config_coded_value_map({
4398             ctype => $format_attr, code => $format_vals});
4399         $resp->{hold}{langs} = $e->search_config_coded_value_map({
4400             ctype => $item_lang_attr, code => $lang_vals});
4401
4402         # find all of the bib records within this metarcord whose
4403         # format / language match the holdable formats on the hold
4404         my ($bre_ids) = $self->method_lookup(
4405             'open-ils.circ.holds.metarecord.filtered_records')->run(
4406                 $hold->target, $hold->holdable_formats,
4407                 $hold->selection_ou, $hold->selection_depth);
4408
4409         # now find all of the 'icon' attributes for the records
4410         $resp->{hold}{icons} = get_batch_ccvms($e, $icon_attr, $bre_ids);
4411         $client->respond($resp);
4412     }
4413
4414     return;
4415 }
4416
4417 __PACKAGE__->register_method(
4418     method        => "copy_has_holds_count",
4419     api_name      => "open-ils.circ.copy.has_holds_count",
4420     authoritative => 1,
4421     signature     => {
4422         desc => q/
4423             Returns the number of holds a paticular copy has
4424         /,
4425         params => [
4426             { desc => 'Authentication Token', type => 'string'},
4427             { desc => 'Copy ID', type => 'number'}
4428         ],
4429         return => {
4430             desc => q/
4431                 Simple count value
4432             /,
4433             type => 'number'
4434         }
4435     }
4436 );
4437
4438 sub copy_has_holds_count {
4439     my( $self, $conn, $auth, $copyid ) = @_;
4440     my $e = new_editor(authtoken=>$auth);
4441     return $e->event unless $e->checkauth;
4442
4443     if( $copyid && $copyid > 0 ) {
4444         my $meth = 'retrieve_action_has_holds_count';
4445         my $data = $e->$meth($copyid);
4446         if($data){
4447                 return $data->count();
4448         }
4449     }
4450     return 0;
4451 }
4452
4453 1;