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

   1 package OpenILS::Application::Circ;
   2 use OpenILS::Application;
   3 use base qw/OpenILS::Application/;
   4 use strict; use warnings;
   5
   6 use OpenILS::Application::Circ::Circulate;
   7 use OpenILS::Application::Circ::Survey;
   8 use OpenILS::Application::Circ::StatCat;
   9 use OpenILS::Application::Circ::Holds;
  10 use OpenILS::Application::Circ::HoldNotify;
  11 use OpenILS::Application::Circ::CreditCard;
  12 use OpenILS::Application::Circ::Money;
  13 use OpenILS::Application::Circ::NonCat;
  14 use OpenILS::Application::Circ::CopyLocations;
  15 use OpenILS::Application::Circ::CircCommon;
  16
  17 use DateTime;
  18 use DateTime::Format::ISO8601;
  19
  20 use OpenILS::Application::AppUtils;
  21
  22 use OpenSRF::Utils qw/:datetime/;
  23 use OpenSRF::AppSession;
  24 use OpenILS::Utils::ModsParser;
  25 use OpenILS::Event;
  26 use OpenSRF::EX qw(:try);
  27 use OpenSRF::Utils::Logger qw(:logger);
  28 use OpenILS::Utils::Fieldmapper;
  29 use OpenILS::Utils::Editor;
  30 use OpenILS::Utils::CStoreEditor q/:funcs/;
  31 use OpenILS::Const qw/:const/;
  32 use OpenSRF::Utils::SettingsClient;
  33 use OpenILS::Application::Cat::AssetCommon;
  34
  35 my $apputils = "OpenILS::Application::AppUtils";
  36 my $U = $apputils;
  37
  38 my $holdcode    = "OpenILS::Application::Circ::Holds";
  39
  40 # ------------------------------------------------------------------------
  41 # Top level Circ package;
  42 # ------------------------------------------------------------------------
  43
  44 sub initialize {
  45         my $self = shift;
  46         OpenILS::Application::Circ::Circulate->initialize();
  47 }
  48
  49
  50 __PACKAGE__->register_method(
  51         method => 'retrieve_circ',
  52         authoritative   => 1,
  53         api_name        => 'open-ils.circ.retrieve',
  54         signature => q/
  55                 Retrieve a circ object by id
  56                 @param authtoken Login session key
  57                 @pararm circid The id of the circ object
  58         /
  59 );
  60 sub retrieve_circ {
  61         my( $s, $c, $a, $i ) = @_;
  62         my $e = new_editor(authtoken => $a);
  63         return $e->event unless $e->checkauth;
  64         my $circ = $e->retrieve_action_circulation($i) or return $e->event;
  65         if( $e->requestor->id ne $circ->usr ) {
  66                 return $e->event unless $e->allowed('VIEW_CIRCULATIONS');
  67         }
  68         return $circ;
  69 }
  70
  71
  72 __PACKAGE__->register_method(
  73         method => 'fetch_circ_mods',
  74         api_name => 'open-ils.circ.circ_modifier.retrieve.all');
  75 sub fetch_circ_mods {
  76     my($self, $conn, $args) = @_;
  77     my $mods = new_editor()->retrieve_all_config_circ_modifier;
  78     return [ map {$_->code} @$mods ] unless $$args{full};
  79     return $mods;
  80 }
  81
  82 __PACKAGE__->register_method(
  83     method => 'ranged_billing_types',
  84     api_name => 'open-ils.circ.billing_type.ranged.retrieve.all');
  85
  86 sub ranged_billing_types {
  87     my($self, $conn, $auth, $org_id, $depth) = @_;
  88     my $e = new_editor(authtoken => $auth);
  89     return $e->event unless $e->checkauth;
  90     return $e->event unless $e->allowed('VIEW_BILLING_TYPE', $org_id);
  91     return $e->search_config_billing_type(
  92         {owner => $U->get_org_full_path($org_id, $depth)});
  93 }
  94
  95
  96
  97 # ------------------------------------------------------------------------
  98 # Returns an array of {circ, record} hashes checked out by the user.
  99 # ------------------------------------------------------------------------
 100 __PACKAGE__->register_method(
 101         method  => "checkouts_by_user",
 102         api_name        => "open-ils.circ.actor.user.checked_out",
 103     stream => 1,
 104         NOTES           => <<"  NOTES");
 105         Returns a list of open circulations as a pile of objects.  Each object
 106         contains the relevant copy, circ, and record
 107         NOTES
 108
 109 sub checkouts_by_user {
 110         my($self, $client, $auth, $user_id) = @_;
 111
 112     my $e = new_editor(authtoken=>$auth);
 113     return $e->event unless $e->checkauth;
 114
 115         my $circ_ids = $e->search_action_circulation(
 116         {   usr => $user_id,
 117             checkin_time => undef,
 118             '-or' => [
 119                 {stop_fines => undef},
 120                 {stop_fines => ['MAXFINES','LONGOVERDUE']}
 121             ]
 122         },
 123         {idlist => 1}
 124     );
 125
 126     for my $id (@$circ_ids) {
 127         my $circ = $e->retrieve_action_circulation([
 128             $id,
 129             {   flesh => 3,
 130                 flesh_fields => {
 131                     circ => ['target_copy'],
 132                     acp => ['call_number'],
 133                     acn => ['record']
 134                 }
 135             }
 136         ]);
 137
 138         # un-flesh for consistency
 139         my $c = $circ->target_copy;
 140         $circ->target_copy($c->id);
 141
 142         my $cn = $c->call_number;
 143         $c->call_number($cn->id);
 144
 145         my $t = $cn->record;
 146         $cn->record($t->id);
 147
 148         $client->respond(
 149             {   circ => $circ,
 150                 copy => $c,
 151                 record => $U->record_to_mvr($t)
 152             }
 153         );
 154     }
 155
 156     return undef;
 157 }
 158
 159
 160
 161 __PACKAGE__->register_method(
 162         method  => "checkouts_by_user_slim",
 163         api_name        => "open-ils.circ.actor.user.checked_out.slim",
 164         NOTES           => <<"  NOTES");
 165         Returns a list of open circulation objects
 166         NOTES
 167
 168 # DEPRECAT ME?? XXX
 169 sub checkouts_by_user_slim {
 170         my( $self, $client, $user_session, $user_id ) = @_;
 171
 172         my( $requestor, $target, $copy, $record, $evt );
 173
 174         ( $requestor, $target, $evt ) =
 175                 $apputils->checkses_requestor( $user_session, $user_id, 'VIEW_CIRCULATIONS');
 176         return $evt if $evt;
 177
 178         $logger->debug( 'User ' . $requestor->id .
 179                 " retrieving checked out items for user " . $target->id );
 180
 181         # XXX Make the call correct..
 182         return $apputils->simplereq(
 183                 'open-ils.cstore',
 184                 "open-ils.cstore.direct.action.open_circulation.search.atomic",
 185                 { usr => $target->id, checkin_time => undef } );
 186 #               { usr => $target->id } );
 187 }
 188
 189
 190 __PACKAGE__->register_method(
 191         method  => "checkouts_by_user_opac",
 192         api_name        => "open-ils.circ.actor.user.checked_out.opac",);
 193
 194 # XXX Deprecate Me
 195 sub checkouts_by_user_opac {
 196         my( $self, $client, $auth, $user_id ) = @_;
 197
 198         my $e = OpenILS::Utils::Editor->new( authtoken => $auth );
 199         return $e->event unless $e->checkauth;
 200         $user_id ||= $e->requestor->id;
 201         return $e->event unless
 202                 my $patron = $e->retrieve_actor_user($user_id);
 203
 204         my $data;
 205         my $search = {usr => $user_id, stop_fines => undef};
 206
 207         if( $user_id ne $e->requestor->id ) {
 208                 $data = $e->search_action_circulation(
 209                         $search, {checkperm=>1, permorg=>$patron->home_ou})
 210                         or return $e->event;
 211
 212         } else {
 213                 $data = $e->search_action_circulation($search);
 214         }
 215
 216         return $data;
 217 }
 218
 219
 220 __PACKAGE__->register_method(
 221         method  => "title_from_transaction",
 222         api_name        => "open-ils.circ.circ_transaction.find_title",
 223         NOTES           => <<"  NOTES");
 224         Returns a mods object for the title that is linked to from the
 225         copy from the hold that created the given transaction
 226         NOTES
 227
 228 sub title_from_transaction {
 229         my( $self, $client, $login_session, $transactionid ) = @_;
 230
 231         my( $user, $circ, $title, $evt );
 232
 233         ( $user, $evt ) = $apputils->checkses( $login_session );
 234         return $evt if $evt;
 235
 236         ( $circ, $evt ) = $apputils->fetch_circulation($transactionid);
 237         return $evt if $evt;
 238
 239         ($title, $evt) = $apputils->fetch_record_by_copy($circ->target_copy);
 240         return $evt if $evt;
 241
 242         return $apputils->record_to_mvr($title);
 243 }
 244
 245 __PACKAGE__->register_method(
 246         method  => "staff_age_to_lost",
 247         api_name        => "open-ils.circ.circulation.age_to_lost",
 248     stream => 1,
 249         signature       => q/
 250         This fires a circ.staff_age_to_lost Action-Trigger event against all
 251         overdue circulations in scope of the specified context library and
 252         user profile, which effectively marks the associated items as Lost.
 253         This is likely to be done at the end of a semester in an academic
 254         library, etc.
 255                 @param auth
 256                 @param args : circ_lib, user_profile
 257         /
 258 );
 259
 260 sub staff_age_to_lost {
 261     my( $self, $conn, $auth, $args ) = @_;
 262
 263     my $orgs = $U->get_org_descendants($args->{'circ_lib'});
 264     my $profiles = $U->fetch_permission_group_descendants($args->{'user_profile'});
 265
 266     my $ses = OpenSRF::AppSession->create('open-ils.trigger');
 267
 268     my $method = 'open-ils.trigger.passive.event.autocreate.batch';
 269     my $hook = 'circ.staff_age_to_lost';
 270     my $context_org = 'circ_lib';
 271     my $opt_granularity = undef;
 272     my $filter = {
 273         "checkin_time" => undef,
 274         "due_date" => { "<" => "now" },
 275         "-or" => [
 276             { "stop_fines"  => ["MAXFINES", "LONGOVERDUE"] }, # FIXME: CLAIMSRETURNED also?
 277             { "stop_fines"  => undef }
 278         ],
 279         "-and" => [
 280             {"-exists" => {
 281                 "select" => {"au" => ["id"]},
 282                 "from"   => "au",
 283                 "where"  => {
 284                     "profile" => $profiles,
 285                     "id" => { "=" => {"+circ" => "usr"} }
 286                 }
 287             }},
 288             {"-exists" => {
 289                 "select" => {"aou" => ["id"]},
 290                 "from"   => "aou",
 291                 "where"  => {
 292                     "-and" => [
 293                         {"id" => { "=" => {"+circ" => "circ_lib"} }},
 294                         {"id" => $orgs}
 295                     ]
 296                 }
 297             }}
 298         ]
 299     };
 300     my $req_timeout = 10800;
 301     my $chunk_size = 100;
 302     my $progress = 1;
 303
 304     my $req = $ses->request($method, $hook, $context_org, $filter, $opt_granularity);
 305     my @event_ids; my @chunked_ids;
 306     while (my $resp = $req->recv(timeout => $req_timeout)) {
 307         push(@event_ids, $resp->content);
 308         push(@chunked_ids, $resp->content);
 309         if (scalar(@chunked_ids) > $chunk_size) {
 310             $conn->respond({'progress'=>$progress++}); # 'event_ids'=>@chunked_ids
 311             @chunked_ids = ();
 312         }
 313     }
 314     if (scalar(@chunked_ids) > 0) {
 315         $conn->respond({'progress'=>$progress++}); # 'event_ids'=>@chunked_ids
 316     }
 317
 318     if(@event_ids) {
 319         $logger->info("staff_age_to_lost: created ".scalar(@event_ids)." events for circ.staff_age_to_lost");
 320         $conn->respond_complete({'total_progress'=>$progress-1,'created'=>scalar(@event_ids)});
 321     } elsif($req->complete) {
 322         $logger->info("staff_age_to_lost: no events to create for circ.staff_age_to_lost");
 323         $conn->respond_complete({'total_progress'=>$progress-1,'created'=>0});
 324     } else {
 325         $logger->warn("staff_age_to_lost: timeout occurred during event creation for circ.staff_age_to_lost");
 326         $conn->respond_complete({'total_progress'=>$progress-1,'error'=>'timeout'});
 327     }
 328
 329     return undef;
 330 }
 331
 332
 333 __PACKAGE__->register_method(
 334         method  => "new_set_circ_lost",
 335         api_name        => "open-ils.circ.circulation.set_lost",
 336         signature       => q/
 337         Sets the copy and related open circulation to lost
 338                 @param auth
 339                 @param args : barcode
 340         /
 341 );
 342
 343
 344 # ---------------------------------------------------------------------
 345 # Sets a circulation to lost.  updates copy status to lost
 346 # applies copy and/or prcoessing fees depending on org settings
 347 # ---------------------------------------------------------------------
 348 sub new_set_circ_lost {
 349     my( $self, $conn, $auth, $args ) = @_;
 350
 351     my $e = new_editor(authtoken=>$auth, xact=>1);
 352     return $e->die_event unless $e->checkauth;
 353
 354     my $copy = $e->search_asset_copy({barcode=>$$args{barcode}, deleted=>'f'})->[0]
 355         or return $e->die_event;
 356
 357     my $evt = OpenILS::Application::Cat::AssetCommon->set_item_lost($e, $copy->id);
 358     return $evt if $evt;
 359
 360     $e->commit;
 361     return 1;
 362 }
 363
 364
 365 __PACKAGE__->register_method(
 366         method  => "set_circ_claims_returned",
 367         api_name        => "open-ils.circ.circulation.set_claims_returned",
 368         signature => {
 369         desc => q/Sets the circ for a given item as claims returned
 370                 If a backdate is provided, overdue fines will be voided
 371                 back to the backdate/,
 372         params => [
 373             {desc => 'Authentication token', type => 'string'},
 374             {desc => 'Arguments, including "barcode" and optional "backdate"', type => 'object'}
 375         ],
 376         return => {desc => q/1 on success, failure event on error, and
 377             PATRON_EXCEEDS_CLAIMS_RETURN_COUNT if the patron exceeds the
 378             configured claims return maximum/}
 379     }
 380 );
 381
 382 __PACKAGE__->register_method(
 383         method  => "set_circ_claims_returned",
 384         api_name        => "open-ils.circ.circulation.set_claims_returned.override",
 385         signature => {
 386         desc => q/This adds support for overrideing the configured max
 387                 claims returned amount.
 388                 @see open-ils.circ.circulation.set_claims_returned./,
 389     }
 390 );
 391
 392 sub set_circ_claims_returned {
 393     my( $self, $conn, $auth, $args, $oargs ) = @_;
 394
 395     my $e = new_editor(authtoken=>$auth, xact=>1);
 396     return $e->die_event unless $e->checkauth;
 397
 398     $oargs = { all => 1 } unless defined $oargs;
 399
 400     my $barcode = $$args{barcode};
 401     my $backdate = $$args{backdate};
 402
 403     my $copy = $e->search_asset_copy({barcode=>$barcode, deleted=>'f'})->[0]
 404         or return $e->die_event;
 405
 406     my $circ = $e->search_action_circulation(
 407         {checkin_time => undef, target_copy => $copy->id})->[0]
 408             or return $e->die_event;
 409
 410     $backdate = $circ->due_date if $$args{use_due_date};
 411
 412     $logger->info("marking circ for item $barcode as claims returned".
 413         (($backdate) ? " with backdate $backdate" : ''));
 414
 415     my $patron = $e->retrieve_actor_user($circ->usr);
 416     my $max_count = $U->ou_ancestor_setting_value(
 417         $circ->circ_lib, 'circ.max_patron_claim_return_count', $e);
 418
 419     # If the patron has too instances of many claims returned,
 420     # require an override to continue.  A configured max of
 421     # 0 means all attempts require an override
 422     if(defined $max_count and $patron->claims_returned_count >= $max_count) {
 423
 424         if($self->api_name =~ /override/ && ($oargs->{all} || grep { $_ eq 'PATRON_EXCEEDS_CLAIMS_RETURN_COUNT' } @{$oargs->{events}})) {
 425
 426             # see if we're allowed to override
 427             return $e->die_event unless
 428                 $e->allowed('SET_CIRC_CLAIMS_RETURNED.override', $circ->circ_lib);
 429
 430         } else {
 431
 432             # exit early and return the max claims return event
 433             $e->rollback;
 434             return OpenILS::Event->new(
 435                 'PATRON_EXCEEDS_CLAIMS_RETURN_COUNT',
 436                 payload => {
 437                     patron_count => $patron->claims_returned_count,
 438                     max_count => $max_count
 439                 }
 440             );
 441         }
 442     }
 443
 444     $e->allowed('SET_CIRC_CLAIMS_RETURNED', $circ->circ_lib)
 445         or return $e->die_event;
 446
 447     $circ->stop_fines(OILS_STOP_FINES_CLAIMSRETURNED);
 448         $circ->stop_fines_time('now') unless $circ->stop_fines_time;
 449
 450     if( $backdate ) {
 451         $backdate = cleanse_ISO8601($backdate);
 452
 453         my $original_date = DateTime::Format::ISO8601->new->parse_datetime(cleanse_ISO8601($circ->due_date));
 454         my $new_date = DateTime::Format::ISO8601->new->parse_datetime($backdate);
 455         $backdate = $new_date->ymd . 'T' . $original_date->strftime('%T%z');
 456
 457         # clean it up once again; need a : in the timezone offset. E.g. -06:00 not -0600
 458         $backdate = cleanse_ISO8601($backdate);
 459
 460         # make it look like the circ stopped at the cliams returned time
 461         $circ->stop_fines_time($backdate);
 462         my $evt = OpenILS::Application::Circ::CircCommon->void_overdues($e, $circ, $backdate);
 463         return $evt if $evt;
 464     }
 465
 466     $e->update_action_circulation($circ) or return $e->die_event;
 467
 468     # see if there is a configured post-claims-return copy status
 469     if(my $stat = $U->ou_ancestor_setting_value($circ->circ_lib, 'circ.claim_return.copy_status')) {
 470             $copy->status($stat);
 471             $copy->edit_date('now');
 472             $copy->editor($e->requestor->id);
 473             $e->update_asset_copy($copy) or return $e->die_event;
 474     }
 475
 476     $e->commit;
 477     return 1;
 478 }
 479
 480
 481 __PACKAGE__->register_method(
 482         method  => "post_checkin_backdate_circ",
 483         api_name        => "open-ils.circ.post_checkin_backdate",
 484         signature => {
 485         desc => q/Back-date an already checked in circulation/,
 486         params => [
 487             {desc => 'Authentication token', type => 'string'},
 488             {desc => 'Circ ID', type => 'number'},
 489             {desc => 'ISO8601 backdate', type => 'string'},
 490         ],
 491         return => {desc => q/1 on success, failure event on error/}
 492     }
 493 );
 494
 495 __PACKAGE__->register_method(
 496         method  => "post_checkin_backdate_circ",
 497         api_name        => "open-ils.circ.post_checkin_backdate.batch",
 498     stream => 1,
 499         signature => {
 500         desc => q/@see open-ils.circ.post_checkin_backdate.  Batch mode/,
 501         params => [
 502             {desc => 'Authentication token', type => 'string'},
 503             {desc => 'List of Circ ID', type => 'array'},
 504             {desc => 'ISO8601 backdate', type => 'string'},
 505         ],
 506         return => {desc => q/Set of: 1 on success, failure event on error/}
 507     }
 508 );
 509
 510
 511 sub post_checkin_backdate_circ {
 512     my( $self, $conn, $auth, $circ_id, $backdate ) = @_;
 513     my $e = new_editor(authtoken=>$auth);
 514     return $e->die_event unless $e->checkauth;
 515     if($self->api_name =~ /batch/) {
 516         foreach my $c (@$circ_id) {
 517             $conn->respond(post_checkin_backdate_circ_impl($e, $c, $backdate));
 518         }
 519     } else {
 520         $conn->respond_complete(post_checkin_backdate_circ_impl($e, $circ_id, $backdate));
 521     }
 522
 523     $e->disconnect;
 524     return undef;
 525 }
 526
 527
 528 sub post_checkin_backdate_circ_impl {
 529     my($e, $circ_id, $backdate) = @_;
 530
 531     $e->xact_begin;
 532
 533     my $circ = $e->retrieve_action_circulation($circ_id)
 534         or return $e->die_event;
 535
 536     # anyone with checkin perms can backdate (more restrictive?)
 537     return $e->die_event unless $e->allowed('COPY_CHECKIN', $circ->circ_lib);
 538
 539     # don't allow back-dating an open circulation
 540     return OpenILS::Event->new('BAD_PARAMS') unless
 541         $backdate and $circ->checkin_time;
 542
 543     # update the checkin and stop_fines times to reflect the new backdate
 544     $circ->stop_fines_time(cleanse_ISO8601($backdate));
 545     $circ->checkin_time(cleanse_ISO8601($backdate));
 546     $e->update_action_circulation($circ) or return $e->die_event;
 547
 548     # now void the overdues "erased" by the back-dating
 549     my $evt = OpenILS::Application::Circ::CircCommon->void_overdues($e, $circ, $backdate);
 550     return $evt if $evt;
 551
 552     # If the circ was closed before and the balance owned !=0, re-open the transaction
 553     $evt = OpenILS::Application::Circ::CircCommon->reopen_xact($e, $circ->id);
 554     return $evt if $evt;
 555
 556     $e->xact_commit;
 557     return 1;
 558 }
 559
 560
 561
 562 __PACKAGE__->register_method (
 563         method          => 'set_circ_due_date',
 564         api_name                => 'open-ils.circ.circulation.due_date.update',
 565         signature       => q/
 566                 Updates the due_date on the given circ
 567                 @param authtoken
 568                 @param circid The id of the circ to update
 569                 @param date The timestamp of the new due date
 570         /
 571 );
 572
 573 sub set_circ_due_date {
 574         my( $self, $conn, $auth, $circ_id, $date ) = @_;
 575
 576     my $e = new_editor(xact=>1, authtoken=>$auth);
 577     return $e->die_event unless $e->checkauth;
 578     my $circ = $e->retrieve_action_circulation($circ_id)
 579         or return $e->die_event;
 580
 581     return $e->die_event unless $e->allowed('CIRC_OVERRIDE_DUE_DATE', $circ->circ_lib);
 582         $date = cleanse_ISO8601($date);
 583
 584     if (!(interval_to_seconds($circ->duration) % 86400)) { # duration is divisible by days
 585         my $original_date = DateTime::Format::ISO8601->new->parse_datetime(cleanse_ISO8601($circ->due_date));
 586         my $new_date = DateTime::Format::ISO8601->new->parse_datetime($date);
 587         $date = cleanse_ISO8601( $new_date->ymd . 'T' . $original_date->strftime('%T%z') );
 588     }
 589
 590         $circ->due_date($date);
 591     $e->update_action_circulation($circ) or return $e->die_event;
 592     $e->commit;
 593
 594     return $circ;
 595 }
 596
 597
 598 __PACKAGE__->register_method(
 599         method          => "create_in_house_use",
 600         api_name                => 'open-ils.circ.in_house_use.create',
 601         signature       =>      q/
 602                 Creates an in-house use action.
 603                 @param $authtoken The login session key
 604                 @param params A hash of params including
 605                         'location' The org unit id where the in-house use occurs
 606                         'copyid' The copy in question
 607                         'count' The number of in-house uses to apply to this copy
 608                 @return An array of id's representing the id's of the newly created
 609                 in-house use objects or an event on an error
 610         /);
 611
 612 __PACKAGE__->register_method(
 613         method          => "create_in_house_use",
 614         api_name                => 'open-ils.circ.non_cat_in_house_use.create',
 615 );
 616
 617
 618 sub create_in_house_use {
 619         my( $self, $client, $auth, $params ) = @_;
 620
 621         my( $evt, $copy );
 622         my $org                 = $params->{location};
 623         my $copyid              = $params->{copyid};
 624         my $count               = $params->{count} || 1;
 625         my $nc_type             = $params->{non_cat_type};
 626         my $use_time    = $params->{use_time} || 'now';
 627
 628         my $e = new_editor(xact=>1,authtoken=>$auth);
 629         return $e->event unless $e->checkauth;
 630         return $e->event unless $e->allowed('CREATE_IN_HOUSE_USE');
 631
 632         my $non_cat = 1 if $self->api_name =~ /non_cat/;
 633
 634         unless( $non_cat ) {
 635                 if( $copyid ) {
 636                         $copy = $e->retrieve_asset_copy($copyid) or return $e->event;
 637                 } else {
 638                         $copy = $e->search_asset_copy({barcode=>$params->{barcode}, deleted => 'f'})->[0]
 639                                 or return $e->event;
 640                         $copyid = $copy->id;
 641                 }
 642         }
 643
 644         if( $use_time ne 'now' ) {
 645                 $use_time = cleanse_ISO8601($use_time);
 646                 $logger->debug("in_house_use setting use time to $use_time");
 647         }
 648
 649         my @ids;
 650         for(1..$count) {
 651
 652                 my $ihu;
 653                 my $method;
 654                 my $cmeth;
 655
 656                 if($non_cat) {
 657                         $ihu = Fieldmapper::action::non_cat_in_house_use->new;
 658                         $ihu->item_type($nc_type);
 659                         $method = 'open-ils.storage.direct.action.non_cat_in_house_use.create';
 660                         $cmeth = "create_action_non_cat_in_house_use";
 661
 662                 } else {
 663                         $ihu = Fieldmapper::action::in_house_use->new;
 664                         $ihu->item($copyid);
 665                         $method = 'open-ils.storage.direct.action.in_house_use.create';
 666                         $cmeth = "create_action_in_house_use";
 667                 }
 668
 669                 $ihu->staff($e->requestor->id);
 670                 $ihu->org_unit($org);
 671                 $ihu->use_time($use_time);
 672
 673                 $ihu = $e->$cmeth($ihu) or return $e->event;
 674                 push( @ids, $ihu->id );
 675         }
 676
 677         $e->commit;
 678         return \@ids;
 679 }
 680
 681
 682
 683
 684
 685 __PACKAGE__->register_method(
 686         method  => "view_circs",
 687         api_name        => "open-ils.circ.copy_checkout_history.retrieve",
 688         notes           => q/
 689                 Retrieves the last X circs for a given copy
 690                 @param authtoken The login session key
 691                 @param copyid The copy to check
 692                 @param count How far to go back in the item history
 693                 @return An array of circ ids
 694         /);
 695
 696 # ----------------------------------------------------------------------
 697 # Returns $count most recent circs.  If count exceeds the configured
 698 # max, use the configured max instead
 699 # ----------------------------------------------------------------------
 700 sub view_circs {
 701         my( $self, $client, $authtoken, $copyid, $count ) = @_;
 702
 703     my $e = new_editor(authtoken => $authtoken);
 704     return $e->event unless $e->checkauth;
 705
 706     my $copy = $e->retrieve_asset_copy([
 707         $copyid,
 708         {   flesh => 1,
 709             flesh_fields => {acp => ['call_number']}
 710         }
 711     ]) or return $e->event;
 712
 713     return $e->event unless $e->allowed(
 714         'VIEW_COPY_CHECKOUT_HISTORY',
 715         ($copy->call_number == OILS_PRECAT_CALL_NUMBER) ?
 716             $copy->circ_lib : $copy->call_number->owning_lib);
 717
 718     my $max_history = $U->ou_ancestor_setting_value(
 719         $e->requestor->ws_ou, 'circ.item_checkout_history.max', $e);
 720
 721     if(defined $max_history) {
 722         $count = $max_history unless defined $count and $count < $max_history;
 723     } else {
 724         $count = 4 unless defined $count;
 725     }
 726
 727     return $e->search_action_circulation([
 728         {target_copy => $copyid},
 729         {limit => $count, order_by => { circ => "xact_start DESC" }}
 730     ]);
 731 }
 732
 733
 734 __PACKAGE__->register_method(
 735         method  => "circ_count",
 736         api_name        => "open-ils.circ.circulation.count",
 737         notes           => q/
 738                 Returns the number of times the item has circulated
 739                 @param copyid The copy to check
 740         /);
 741
 742 sub circ_count {
 743         my( $self, $client, $copyid, $range ) = @_;
 744         my $e = OpenILS::Utils::Editor->new;
 745         return $e->request('open-ils.storage.asset.copy.circ_count', $copyid, $range);
 746 }
 747
 748
 749
 750 __PACKAGE__->register_method(
 751         method          => 'fetch_notes',
 752         authoritative   => 1,
 753         api_name                => 'open-ils.circ.copy_note.retrieve.all',
 754         signature       => q/
 755                 Returns an array of copy note objects.
 756                 @param args A named hash of parameters including:
 757                         authtoken       : Required if viewing non-public notes
 758                         itemid          : The id of the item whose notes we want to retrieve
 759                         pub                     : True if all the caller wants are public notes
 760                 @return An array of note objects
 761         /);
 762
 763 __PACKAGE__->register_method(
 764         method          => 'fetch_notes',
 765         api_name                => 'open-ils.circ.call_number_note.retrieve.all',
 766         signature       => q/@see open-ils.circ.copy_note.retrieve.all/);
 767
 768 __PACKAGE__->register_method(
 769         method          => 'fetch_notes',
 770         api_name                => 'open-ils.circ.title_note.retrieve.all',
 771         signature       => q/@see open-ils.circ.copy_note.retrieve.all/);
 772
 773
 774 # NOTE: VIEW_COPY/VOLUME/TITLE_NOTES perms should always be global
 775 sub fetch_notes {
 776         my( $self, $connection, $args ) = @_;
 777
 778         my $id = $$args{itemid};
 779         my $authtoken = $$args{authtoken};
 780         my( $r, $evt);
 781
 782         if( $self->api_name =~ /copy/ ) {
 783                 if( $$args{pub} ) {
 784                         return $U->cstorereq(
 785                                 'open-ils.cstore.direct.asset.copy_note.search.atomic',
 786                                 { owning_copy => $id, pub => 't' } );
 787                 } else {
 788                         ( $r, $evt ) = $U->checksesperm($authtoken, 'VIEW_COPY_NOTES');
 789                         return $evt if $evt;
 790                         return $U->cstorereq(
 791                                 'open-ils.cstore.direct.asset.copy_note.search.atomic', {owning_copy => $id} );
 792                 }
 793
 794         } elsif( $self->api_name =~ /call_number/ ) {
 795                 if( $$args{pub} ) {
 796                         return $U->cstorereq(
 797                                 'open-ils.cstore.direct.asset.call_number_note.search.atomic',
 798                                 { call_number => $id, pub => 't' } );
 799                 } else {
 800                         ( $r, $evt ) = $U->checksesperm($authtoken, 'VIEW_VOLUME_NOTES');
 801                         return $evt if $evt;
 802                         return $U->cstorereq(
 803                                 'open-ils.cstore.direct.asset.call_number_note.search.atomic', { call_number => $id } );
 804                 }
 805
 806         } elsif( $self->api_name =~ /title/ ) {
 807                 if( $$args{pub} ) {
 808                         return $U->cstorereq(
 809                                 'open-ils.cstore.direct.bilbio.record_note.search.atomic',
 810                                 { record => $id, pub => 't' } );
 811                 } else {
 812                         ( $r, $evt ) = $U->checksesperm($authtoken, 'VIEW_TITLE_NOTES');
 813                         return $evt if $evt;
 814                         return $U->cstorereq(
 815                                 'open-ils.cstore.direct.biblio.record_note.search.atomic', { record => $id } );
 816                 }
 817         }
 818
 819         return undef;
 820 }
 821
 822 __PACKAGE__->register_method(
 823         method  => 'has_notes',
 824         api_name        => 'open-ils.circ.copy.has_notes');
 825 __PACKAGE__->register_method(
 826         method  => 'has_notes',
 827         api_name        => 'open-ils.circ.call_number.has_notes');
 828 __PACKAGE__->register_method(
 829         method  => 'has_notes',
 830         api_name        => 'open-ils.circ.title.has_notes');
 831
 832
 833 sub has_notes {
 834         my( $self, $conn, $authtoken, $id ) = @_;
 835         my $editor = OpenILS::Utils::Editor->new(authtoken => $authtoken);
 836         return $editor->event unless $editor->checkauth;
 837
 838         my $n = $editor->search_asset_copy_note(
 839                 {owning_copy=>$id}, {idlist=>1}) if $self->api_name =~ /copy/;
 840
 841         $n = $editor->search_asset_call_number_note(
 842                 {call_number=>$id}, {idlist=>1}) if $self->api_name =~ /call_number/;
 843
 844         $n = $editor->search_biblio_record_note(
 845                 {record=>$id}, {idlist=>1}) if $self->api_name =~ /title/;
 846
 847         return scalar @$n;
 848 }
 849
 850
 851
 852 __PACKAGE__->register_method(
 853         method          => 'create_copy_note',
 854         api_name                => 'open-ils.circ.copy_note.create',
 855         signature       => q/
 856                 Creates a new copy note
 857                 @param authtoken The login session key
 858                 @param note     The note object to create
 859                 @return The id of the new note object
 860         /);
 861
 862 sub create_copy_note {
 863         my( $self, $connection, $authtoken, $note ) = @_;
 864
 865         my $e = new_editor(xact=>1, authtoken=>$authtoken);
 866         return $e->event unless $e->checkauth;
 867         my $copy = $e->retrieve_asset_copy(
 868                 [
 869                         $note->owning_copy,
 870                         {       flesh => 1,
 871                                 flesh_fields => { 'acp' => ['call_number'] }
 872                         }
 873                 ]
 874         );
 875
 876         return $e->event unless
 877                 $e->allowed('CREATE_COPY_NOTE', $copy->call_number->owning_lib);
 878
 879         $note->create_date('now');
 880         $note->creator($e->requestor->id);
 881         $note->pub( ($U->is_true($note->pub)) ? 't' : 'f' );
 882         $note->clear_id;
 883
 884         $e->create_asset_copy_note($note) or return $e->event;
 885         $e->commit;
 886         return $note->id;
 887 }
 888
 889
 890 __PACKAGE__->register_method(
 891         method          => 'delete_copy_note',
 892         api_name                =>      'open-ils.circ.copy_note.delete',
 893         signature       => q/
 894                 Deletes an existing copy note
 895                 @param authtoken The login session key
 896                 @param noteid The id of the note to delete
 897                 @return 1 on success - Event otherwise.
 898                 /);
 899 sub delete_copy_note {
 900         my( $self, $conn, $authtoken, $noteid ) = @_;
 901
 902         my $e = new_editor(xact=>1, authtoken=>$authtoken);
 903         return $e->die_event unless $e->checkauth;
 904
 905         my $note = $e->retrieve_asset_copy_note([
 906                 $noteid,
 907                 { flesh => 2,
 908                         flesh_fields => {
 909                                 'acpn' => [ 'owning_copy' ],
 910                                 'acp' => [ 'call_number' ],
 911                         }
 912                 }
 913         ]) or return $e->die_event;
 914
 915         if( $note->creator ne $e->requestor->id ) {
 916                 return $e->die_event unless
 917                         $e->allowed('DELETE_COPY_NOTE', $note->owning_copy->call_number->owning_lib);
 918         }
 919
 920         $e->delete_asset_copy_note($note) or return $e->die_event;
 921         $e->commit;
 922         return 1;
 923 }
 924
 925
 926 __PACKAGE__->register_method(
 927         method => 'age_hold_rules',
 928         api_name        =>  'open-ils.circ.config.rules.age_hold_protect.retrieve.all',
 929 );
 930
 931 sub age_hold_rules {
 932         my( $self, $conn ) = @_;
 933         return new_editor()->retrieve_all_config_rules_age_hold_protect();
 934 }
 935
 936
 937
 938 __PACKAGE__->register_method(
 939         method => 'copy_details_barcode',
 940     authoritative => 1,
 941         api_name => 'open-ils.circ.copy_details.retrieve.barcode');
 942 sub copy_details_barcode {
 943         my( $self, $conn, $auth, $barcode ) = @_;
 944     my $e = new_editor();
 945     my $cid = $e->search_asset_copy({barcode=>$barcode, deleted=>'f'}, {idlist=>1})->[0];
 946     return $e->event unless $cid;
 947         return copy_details( $self, $conn, $auth, $cid );
 948 }
 949
 950
 951 __PACKAGE__->register_method(
 952         method => 'copy_details',
 953         api_name => 'open-ils.circ.copy_details.retrieve');
 954
 955 sub copy_details {
 956         my( $self, $conn, $auth, $copy_id ) = @_;
 957         my $e = new_editor(authtoken=>$auth);
 958         return $e->event unless $e->checkauth;
 959
 960         my $flesh = { flesh => 1 };
 961
 962         my $copy = $e->retrieve_asset_copy(
 963                 [
 964                         $copy_id,
 965                         {
 966                                 flesh => 2,
 967                                 flesh_fields => {
 968                                         acp => ['call_number','parts','peer_record_maps'],
 969                                         acn => ['record','prefix','suffix','label_class']
 970                                 }
 971                         }
 972                 ]) or return $e->event;
 973
 974
 975         # De-flesh the copy for backwards compatibility
 976         my $mvr;
 977         my $vol = $copy->call_number;
 978         if( ref $vol ) {
 979                 $copy->call_number($vol->id);
 980                 my $record = $vol->record;
 981                 if( ref $record ) {
 982                         $vol->record($record->id);
 983                         $mvr = $U->record_to_mvr($record);
 984                 }
 985         }
 986
 987
 988         my $hold = $e->search_action_hold_request(
 989                 {
 990                         current_copy            => $copy_id,
 991                         capture_time            => { "!=" => undef },
 992                         fulfillment_time        => undef,
 993                         cancel_time                     => undef,
 994                 }
 995         )->[0];
 996
 997         OpenILS::Application::Circ::Holds::flesh_hold_transits([$hold]) if $hold;
 998
 999         my $transit = $e->search_action_transit_copy(
1000                 { target_copy => $copy_id, dest_recv_time => undef } )->[0];
1001
1002         # find the latest circ, open or closed
1003         my $circ = $e->search_action_circulation(
1004                 [
1005                         { target_copy => $copy_id },
1006                         {
1007                 flesh => 1,
1008                 flesh_fields => {
1009                     circ => [
1010                         'workstation',
1011                         'checkin_workstation',
1012                         'duration_rule',
1013                         'max_fine_rule',
1014                         'recurring_fine_rule'
1015                     ]
1016                 },
1017                 order_by => { circ => 'xact_start desc' },
1018                 limit => 1
1019             }
1020                 ]
1021         )->[0];
1022
1023
1024         return {
1025                 copy            => $copy,
1026                 hold            => $hold,
1027                 transit => $transit,
1028                 circ            => $circ,
1029                 volume  => $vol,
1030                 mvr             => $mvr,
1031         };
1032 }
1033
1034
1035
1036
1037 __PACKAGE__->register_method(
1038         method => 'mark_item',
1039         api_name => 'open-ils.circ.mark_item_damaged',
1040         signature       => q/
1041                 Changes the status of a copy to "damaged". Requires MARK_ITEM_DAMAGED permission.
1042                 @param authtoken The login session key
1043                 @param copy_id The ID of the copy to mark as damaged
1044                 @return 1 on success - Event otherwise.
1045                 /
1046 );
1047 __PACKAGE__->register_method(
1048         method => 'mark_item',
1049         api_name => 'open-ils.circ.mark_item_missing',
1050         signature       => q/
1051                 Changes the status of a copy to "missing". Requires MARK_ITEM_MISSING permission.
1052                 @param authtoken The login session key
1053                 @param copy_id The ID of the copy to mark as missing
1054                 @return 1 on success - Event otherwise.
1055                 /
1056 );
1057 __PACKAGE__->register_method(
1058         method => 'mark_item',
1059         api_name => 'open-ils.circ.mark_item_bindery',
1060         signature       => q/
1061                 Changes the status of a copy to "bindery". Requires MARK_ITEM_BINDERY permission.
1062                 @param authtoken The login session key
1063                 @param copy_id The ID of the copy to mark as bindery
1064                 @return 1 on success - Event otherwise.
1065                 /
1066 );
1067 __PACKAGE__->register_method(
1068         method => 'mark_item',
1069         api_name => 'open-ils.circ.mark_item_on_order',
1070         signature       => q/
1071                 Changes the status of a copy to "on order". Requires MARK_ITEM_ON_ORDER permission.
1072                 @param authtoken The login session key
1073                 @param copy_id The ID of the copy to mark as on order
1074                 @return 1 on success - Event otherwise.
1075                 /
1076 );
1077 __PACKAGE__->register_method(
1078         method => 'mark_item',
1079         api_name => 'open-ils.circ.mark_item_ill',
1080         signature       => q/
1081                 Changes the status of a copy to "inter-library loan". Requires MARK_ITEM_ILL permission.
1082                 @param authtoken The login session key
1083                 @param copy_id The ID of the copy to mark as inter-library loan
1084                 @return 1 on success - Event otherwise.
1085                 /
1086 );
1087 __PACKAGE__->register_method(
1088         method => 'mark_item',
1089         api_name => 'open-ils.circ.mark_item_cataloging',
1090         signature       => q/
1091                 Changes the status of a copy to "cataloging". Requires MARK_ITEM_CATALOGING permission.
1092                 @param authtoken The login session key
1093                 @param copy_id The ID of the copy to mark as cataloging
1094                 @return 1 on success - Event otherwise.
1095                 /
1096 );
1097 __PACKAGE__->register_method(
1098         method => 'mark_item',
1099         api_name => 'open-ils.circ.mark_item_reserves',
1100         signature       => q/
1101                 Changes the status of a copy to "reserves". Requires MARK_ITEM_RESERVES permission.
1102                 @param authtoken The login session key
1103                 @param copy_id The ID of the copy to mark as reserves
1104                 @return 1 on success - Event otherwise.
1105                 /
1106 );
1107 __PACKAGE__->register_method(
1108         method => 'mark_item',
1109         api_name => 'open-ils.circ.mark_item_discard',
1110         signature       => q/
1111                 Changes the status of a copy to "discard". Requires MARK_ITEM_DISCARD permission.
1112                 @param authtoken The login session key
1113                 @param copy_id The ID of the copy to mark as discard
1114                 @return 1 on success - Event otherwise.
1115                 /
1116 );
1117
1118 sub mark_item {
1119         my( $self, $conn, $auth, $copy_id, $args ) = @_;
1120         my $e = new_editor(authtoken=>$auth, xact =>1);
1121         return $e->die_event unless $e->checkauth;
1122     $args ||= {};
1123
1124     my $copy = $e->retrieve_asset_copy([
1125         $copy_id,
1126         {flesh => 1, flesh_fields => {'acp' => ['call_number']}}])
1127             or return $e->die_event;
1128
1129     my $owning_lib =
1130         ($copy->call_number->id == OILS_PRECAT_CALL_NUMBER) ?
1131             $copy->circ_lib : $copy->call_number->owning_lib;
1132
1133         my $perm = 'MARK_ITEM_MISSING';
1134         my $stat = OILS_COPY_STATUS_MISSING;
1135
1136         if( $self->api_name =~ /damaged/ ) {
1137                 $perm = 'MARK_ITEM_DAMAGED';
1138                 $stat = OILS_COPY_STATUS_DAMAGED;
1139         my $evt = handle_mark_damaged($e, $copy, $owning_lib, $args);
1140         return $evt if $evt;
1141
1142         } elsif ( $self->api_name =~ /bindery/ ) {
1143                 $perm = 'MARK_ITEM_BINDERY';
1144                 $stat = OILS_COPY_STATUS_BINDERY;
1145         } elsif ( $self->api_name =~ /on_order/ ) {
1146                 $perm = 'MARK_ITEM_ON_ORDER';
1147                 $stat = OILS_COPY_STATUS_ON_ORDER;
1148         } elsif ( $self->api_name =~ /ill/ ) {
1149                 $perm = 'MARK_ITEM_ILL';
1150                 $stat = OILS_COPY_STATUS_ILL;
1151         } elsif ( $self->api_name =~ /cataloging/ ) {
1152                 $perm = 'MARK_ITEM_CATALOGING';
1153                 $stat = OILS_COPY_STATUS_CATALOGING;
1154         } elsif ( $self->api_name =~ /reserves/ ) {
1155                 $perm = 'MARK_ITEM_RESERVES';
1156                 $stat = OILS_COPY_STATUS_RESERVES;
1157         } elsif ( $self->api_name =~ /discard/ ) {
1158                 $perm = 'MARK_ITEM_DISCARD';
1159                 $stat = OILS_COPY_STATUS_DISCARD;
1160         }
1161
1162     # caller may proceed if either perm is allowed
1163     return $e->die_event unless $e->allowed([$perm, 'UPDATE_COPY'], $owning_lib);
1164
1165         $copy->status($stat);
1166         $copy->edit_date('now');
1167         $copy->editor($e->requestor->id);
1168
1169         $e->update_asset_copy($copy) or return $e->die_event;
1170
1171         my $holds = $e->search_action_hold_request(
1172                 {
1173                         current_copy => $copy->id,
1174                         fulfillment_time => undef,
1175                         cancel_time => undef,
1176                 }
1177         );
1178
1179         $e->commit;
1180
1181         if( $self->api_name =~ /damaged/ ) {
1182         # now that we've committed the changes, create related A/T events
1183         my $ses = OpenSRF::AppSession->create('open-ils.trigger');
1184         $ses->request('open-ils.trigger.event.autocreate', 'damaged', $copy, $owning_lib);
1185     }
1186
1187         $logger->debug("resetting holds that target the marked copy");
1188         OpenILS::Application::Circ::Holds->_reset_hold($e->requestor, $_) for @$holds;
1189
1190         return 1;
1191 }
1192
1193 sub handle_mark_damaged {
1194     my($e, $copy, $owning_lib, $args) = @_;
1195
1196     my $apply = $args->{apply_fines} || '';
1197     return undef if $apply eq 'noapply';
1198
1199     my $new_amount = $args->{override_amount};
1200     my $new_btype = $args->{override_btype};
1201     my $new_note = $args->{override_note};
1202
1203     # grab the last circulation
1204     my $circ = $e->search_action_circulation([
1205         {   target_copy => $copy->id},
1206         {   limit => 1,
1207             order_by => {circ => "xact_start DESC"},
1208             flesh => 2,
1209             flesh_fields => {circ => ['target_copy', 'usr'], au => ['card']}
1210         }
1211     ])->[0];
1212
1213     return undef unless $circ;
1214
1215     my $charge_price = $U->ou_ancestor_setting_value(
1216         $owning_lib, 'circ.charge_on_damaged', $e);
1217
1218     my $proc_fee = $U->ou_ancestor_setting_value(
1219         $owning_lib, 'circ.damaged_item_processing_fee', $e) || 0;
1220
1221     my $void_overdue = $U->ou_ancestor_setting_value(
1222         $owning_lib, 'circ.damaged.void_ovedue', $e) || 0;
1223
1224     return undef unless $charge_price or $proc_fee;
1225
1226     my $copy_price = ($charge_price) ? $U->get_copy_price($e, $copy) : 0;
1227     my $total = $copy_price + $proc_fee;
1228
1229     if($apply) {
1230
1231         if($new_amount and $new_btype) {
1232
1233             # Allow staff to override the amount to charge for a damaged item
1234             # Consider the case where the item is only partially damaged
1235             # This value is meant to take the place of the item price and
1236             # optional processing fee.
1237
1238             my $evt = OpenILS::Application::Circ::CircCommon->create_bill(
1239                 $e, $new_amount, $new_btype, 'Damaged Item Override', $circ->id, $new_note);
1240             return $evt if $evt;
1241
1242         } else {
1243
1244             if($charge_price and $copy_price) {
1245                 my $evt = OpenILS::Application::Circ::CircCommon->create_bill(
1246                     $e, $copy_price, 7, 'Damaged Item', $circ->id);
1247                 return $evt if $evt;
1248             }
1249
1250             if($proc_fee) {
1251                 my $evt = OpenILS::Application::Circ::CircCommon->create_bill(
1252                     $e, $proc_fee, 8, 'Damaged Item Processing Fee', $circ->id);
1253                 return $evt if $evt;
1254             }
1255         }
1256
1257         # the assumption is that you would not void the overdues unless you
1258         # were also charging for the item and/or applying a processing fee
1259         if($void_overdue) {
1260             my $evt = OpenILS::Application::Circ::CircCommon->void_overdues($e, $circ);
1261             return $evt if $evt;
1262         }
1263
1264         my $evt = OpenILS::Application::Circ::CircCommon->reopen_xact($e, $circ->id);
1265         return $evt if $evt;
1266
1267         my $ses = OpenSRF::AppSession->create('open-ils.trigger');
1268         $ses->request('open-ils.trigger.event.autocreate', 'checkout.damaged', $circ, $circ->circ_lib);
1269
1270         my $evt2 = OpenILS::Utils::Penalty->calculate_penalties($e, $circ->usr->id, $e->requestor->ws_ou);
1271         return $evt2 if $evt2;
1272
1273         return undef;
1274
1275     } else {
1276         return OpenILS::Event->new('DAMAGE_CHARGE',
1277             payload => {
1278                 circ => $circ,
1279                 charge => $total
1280             }
1281         );
1282     }
1283 }
1284
1285
1286
1287 # ----------------------------------------------------------------------
1288 __PACKAGE__->register_method(
1289     method => 'mark_item_missing_pieces',
1290     api_name => 'open-ils.circ.mark_item_missing_pieces',
1291     signature   => q/
1292         Changes the status of a copy to "damaged" or to a custom status based on the
1293         circ.missing_pieces.copy_status org unit setting. Requires MARK_ITEM_MISSING_PIECES
1294         permission.
1295         @param authtoken The login session key
1296         @param copy_id The ID of the copy to mark as damaged
1297         @return Success event with circ and copy objects in the payload, or error Event otherwise.
1298         /
1299 );
1300
1301 sub mark_item_missing_pieces {
1302         my( $self, $conn, $auth, $copy_id, $args ) = @_;
1303     ### FIXME: We're starting a transaction here, but we're doing a lot of things outside of the transaction
1304     ### FIXME: Even better, we're going to use two transactions, the first to affect pertinent holds before checkout can
1305
1306         my $e2 = new_editor(authtoken=>$auth, xact =>1);
1307         return $e2->die_event unless $e2->checkauth;
1308     $args ||= {};
1309
1310     my $copy = $e2->retrieve_asset_copy([
1311         $copy_id,
1312         {flesh => 1, flesh_fields => {'acp' => ['call_number']}}])
1313             or return $e2->die_event;
1314
1315     my $owning_lib =
1316         ($copy->call_number->id == OILS_PRECAT_CALL_NUMBER) ?
1317             $copy->circ_lib : $copy->call_number->owning_lib;
1318
1319     return $e2->die_event unless $e2->allowed('MARK_ITEM_MISSING_PIECES', $owning_lib);
1320
1321     #### grab the last circulation
1322     my $circ = $e2->search_action_circulation([
1323         {   target_copy => $copy->id},
1324         {   limit => 1,
1325             order_by => {circ => "xact_start DESC"}
1326         }
1327     ])->[0];
1328
1329     if (!$circ) {
1330         $logger->info('open-ils.circ.mark_item_missing_pieces: no previous checkout');
1331         $e2->rollback;
1332         return OpenILS::Event->new('ACTION_CIRCULATION_NOT_FOUND',{'copy'=>$copy});
1333     }
1334
1335         my $holds = $e2->search_action_hold_request(
1336                 {
1337                         current_copy => $copy->id,
1338                         fulfillment_time => undef,
1339                         cancel_time => undef,
1340                 }
1341         );
1342
1343     $logger->debug("resetting holds that target the marked copy");
1344     OpenILS::Application::Circ::Holds->_reset_hold($e2->requestor, $_) for @$holds;
1345
1346
1347         if (! $e2->commit) {
1348         return $e2->die_event;
1349     }
1350
1351         my $e = new_editor(authtoken=>$auth, xact =>1);
1352         return $e->die_event unless $e->checkauth;
1353
1354     if (! $circ->checkin_time) { # if circ active, attempt renew
1355         my ($res) = $self->method_lookup('open-ils.circ.renew')->run($e->authtoken,{'copy_id'=>$circ->target_copy});
1356         if (ref $res ne 'ARRAY') { $res = [ $res ]; }
1357         if ( $res->[0]->{textcode} eq 'SUCCESS' ) {
1358             $circ = $res->[0]->{payload}{'circ'};
1359             $circ->target_copy( $copy->id );
1360             $logger->info('open-ils.circ.mark_item_missing_pieces: successful renewal');
1361         } else {
1362             $logger->info('open-ils.circ.mark_item_missing_pieces: non-successful renewal');
1363         }
1364     } else {
1365
1366         my $co_params = {
1367             'copy_id'=>$circ->target_copy,
1368             'patron_id'=>$circ->usr,
1369             'skip_deposit_fee'=>1,
1370             'skip_rental_fee'=>1
1371         };
1372
1373         if ($U->ou_ancestor_setting_value($e->requestor->ws_ou, 'circ.block_renews_for_holds')) {
1374
1375             my ($hold, undef, $retarget) = $holdcode->find_nearest_permitted_hold(
1376                 $e, $copy, $e->requestor, 1 );
1377
1378             if ($hold) { # needed for hold? then due now
1379
1380                 $logger->info('open-ils.circ.mark_item_missing_pieces: item needed for hold, shortening due date');
1381                 my $due_date = DateTime->now(time_zone => 'local');
1382                 $co_params->{'due_date'} = cleanse_ISO8601( $due_date->strftime('%FT%T%z') );
1383             } else {
1384                 $logger->info('open-ils.circ.mark_item_missing_pieces: item not needed for hold');
1385             }
1386         }
1387
1388         my ($res) = $self->method_lookup('open-ils.circ.checkout.full.override')->run($e->authtoken,$co_params,{ all => 1 });
1389         if (ref $res ne 'ARRAY') { $res = [ $res ]; }
1390         if ( $res->[0]->{textcode} eq 'SUCCESS' ) {
1391             $logger->info('open-ils.circ.mark_item_missing_pieces: successful checkout');
1392             $circ = $res->[0]->{payload}{'circ'};
1393         } else {
1394             $logger->info('open-ils.circ.mark_item_missing_pieces: non-successful checkout');
1395             $e->rollback;
1396             return $res;
1397         }
1398     }
1399
1400     ### Update the item status
1401
1402     my $custom_stat = $U->ou_ancestor_setting_value(
1403         $owning_lib, 'circ.missing_pieces.copy_status', $e);
1404     my $stat = $custom_stat || OILS_COPY_STATUS_DAMAGED;
1405
1406     my $ses = OpenSRF::AppSession->create('open-ils.trigger');
1407     $ses->request('open-ils.trigger.event.autocreate', 'missing_pieces', $copy, $owning_lib);
1408
1409         $copy->status($stat);
1410         $copy->edit_date('now');
1411         $copy->editor($e->requestor->id);
1412
1413         $e->update_asset_copy($copy) or return $e->die_event;
1414
1415         if ($e->commit) {
1416
1417         my $ses = OpenSRF::AppSession->create('open-ils.trigger');
1418         $ses->request('open-ils.trigger.event.autocreate', 'circ.missing_pieces', $circ, $circ->circ_lib);
1419
1420         return OpenILS::Event->new('SUCCESS',
1421             payload => {
1422                 circ => $circ,
1423                 copy => $copy,
1424                 slip => $U->fire_object_event(undef, 'circ.format.missing_pieces.slip.print', $circ, $circ->circ_lib),
1425                 letter => $U->fire_object_event(undef, 'circ.format.missing_pieces.letter.print', $circ, $circ->circ_lib)
1426             }
1427         );
1428
1429     } else {
1430         return $e->die_event;
1431     }
1432 }
1433
1434
1435
1436
1437
1438 # ----------------------------------------------------------------------
1439 __PACKAGE__->register_method(
1440         method => 'magic_fetch',
1441         api_name => 'open-ils.agent.fetch'
1442 );
1443
1444 my @FETCH_ALLOWED = qw/ aou aout acp acn bre /;
1445
1446 sub magic_fetch {
1447         my( $self, $conn, $auth, $args ) = @_;
1448         my $e = new_editor( authtoken => $auth );
1449         return $e->event unless $e->checkauth;
1450
1451         my $hint = $$args{hint};
1452         my $id  = $$args{id};
1453
1454         # Is the call allowed to fetch this type of object?
1455         return undef unless grep { $_ eq $hint } @FETCH_ALLOWED;
1456
1457         # Find the class the implements the given hint
1458         my ($class) = grep {
1459                 $Fieldmapper::fieldmap->{$_}{hint} eq $hint } Fieldmapper->classes;
1460
1461         $class =~ s/Fieldmapper:://og;
1462         $class =~ s/::/_/og;
1463         my $method = "retrieve_$class";
1464
1465         my $obj = $e->$method($id) or return $e->event;
1466         return $obj;
1467 }
1468 # ----------------------------------------------------------------------
1469
1470
1471 __PACKAGE__->register_method(
1472         method  => "fleshed_circ_retrieve",
1473     authoritative => 1,
1474         api_name        => "open-ils.circ.fleshed.retrieve",);
1475
1476 sub fleshed_circ_retrieve {
1477         my( $self, $client, $id ) = @_;
1478         my $e = new_editor();
1479         my $circ = $e->retrieve_action_circulation(
1480                 [
1481                         $id,
1482                         {
1483                                 flesh                           => 4,
1484                                 flesh_fields    => {
1485                                         circ => [ qw/ target_copy / ],
1486                                         acp => [ qw/ location status stat_cat_entry_copy_maps notes age_protect call_number parts / ],
1487                                         ascecm => [ qw/ stat_cat stat_cat_entry / ],
1488                                         acn => [ qw/ record / ],
1489                                 }
1490                         }
1491                 ]
1492         ) or return $e->event;
1493
1494         my $copy = $circ->target_copy;
1495         my $vol = $copy->call_number;
1496         my $rec = $circ->target_copy->call_number->record;
1497
1498         $vol->record($rec->id);
1499         $copy->call_number($vol->id);
1500         $circ->target_copy($copy->id);
1501
1502         my $mvr;
1503
1504         if( $rec->id == OILS_PRECAT_RECORD ) {
1505                 $rec = undef;
1506                 $vol = undef;
1507         } else {
1508                 $mvr = $U->record_to_mvr($rec);
1509                 $rec->marc(''); # drop the bulky marc data
1510         }
1511
1512         return {
1513                 circ => $circ,
1514                 copy => $copy,
1515                 volume => $vol,
1516                 record => $rec,
1517                 mvr => $mvr,
1518         };
1519 }
1520
1521
1522
1523 __PACKAGE__->register_method(
1524         method  => "test_batch_circ_events",
1525         api_name        => "open-ils.circ.trigger_event_by_def_and_barcode.fire"
1526 );
1527
1528 #  method for testing the behavior of a given event definition
1529 sub test_batch_circ_events {
1530     my($self, $conn, $auth, $event_def, $barcode) = @_;
1531
1532     my $e = new_editor(authtoken => $auth);
1533         return $e->event unless $e->checkauth;
1534     return $e->event unless $e->allowed('VIEW_CIRCULATIONS');
1535
1536     my $copy = $e->search_asset_copy({barcode => $barcode, deleted => 'f'})->[0]
1537         or return $e->event;
1538
1539     my $circ = $e->search_action_circulation(
1540         {target_copy => $copy->id, checkin_time => undef})->[0]
1541         or return $e->event;
1542
1543     return undef unless $circ;
1544
1545     return $U->fire_object_event($event_def, undef, $circ, $e->requestor->ws_ou)
1546 }
1547
1548
1549 __PACKAGE__->register_method(
1550         method  => "fire_circ_events",
1551         api_name        => "open-ils.circ.fire_circ_trigger_events",
1552     signature => q/
1553         General event def runner for circ objects.  If no event def ID
1554         is provided, the hook will be used to find the best event_def
1555         match based on the context org unit
1556     /
1557 );
1558
1559 __PACKAGE__->register_method(
1560         method  => "fire_circ_events",
1561         api_name        => "open-ils.circ.fire_hold_trigger_events",
1562     signature => q/
1563         General event def runner for hold objects.  If no event def ID
1564         is provided, the hook will be used to find the best event_def
1565         match based on the context org unit
1566     /
1567 );
1568
1569 __PACKAGE__->register_method(
1570         method  => "fire_circ_events",
1571         api_name        => "open-ils.circ.fire_user_trigger_events",
1572     signature => q/
1573         General event def runner for user objects.  If no event def ID
1574         is provided, the hook will be used to find the best event_def
1575         match based on the context org unit
1576     /
1577 );
1578
1579
1580 sub fire_circ_events {
1581     my($self, $conn, $auth, $org_id, $event_def, $hook, $granularity, $target_ids, $user_data) = @_;
1582
1583     my $e = new_editor(authtoken => $auth, xact => 1);
1584         return $e->event unless $e->checkauth;
1585
1586     my $targets;
1587
1588     if($self->api_name =~ /hold/) {
1589         return $e->event unless $e->allowed('VIEW_HOLD', $org_id);
1590         $targets = $e->batch_retrieve_action_hold_request($target_ids);
1591     } elsif($self->api_name =~ /user/) {
1592         return $e->event unless $e->allowed('VIEW_USER', $org_id);
1593         $targets = $e->batch_retrieve_actor_user($target_ids);
1594     } else {
1595         return $e->event unless $e->allowed('VIEW_CIRCULATIONS', $org_id);
1596         $targets = $e->batch_retrieve_action_circulation($target_ids);
1597     }
1598     $e->rollback; # FIXME using transaction because of pgpool/slony setups, but not
1599                   # simply making this method authoritative because of weirdness
1600                   # with transaction handling in A/T code that causes rollback
1601                   # failure down the line if handling many targets
1602
1603     return undef unless @$targets;
1604     return $U->fire_object_event($event_def, $hook, $targets, $org_id, $granularity, $user_data);
1605 }
1606
1607 __PACKAGE__->register_method(
1608         method  => "user_payments_list",
1609         api_name        => "open-ils.circ.user_payments.filtered.batch",
1610     stream => 1,
1611         signature => {
1612         desc => q/Returns a fleshed, date-limited set of all payments a user
1613                 has made.  By default, ordered by payment date.  Optionally
1614                 ordered by other columns in the top-level "mp" object/,
1615         params => [
1616             {desc => 'Authentication token', type => 'string'},
1617             {desc => 'User ID', type => 'number'},
1618             {desc => 'Order by column(s), optional.  Array of "mp" class columns', type => 'array'}
1619         ],
1620         return => {desc => q/List of "mp" objects, fleshed with the billable transaction
1621             and the related fully-realized payment object (e.g money.cash_payment)/}
1622     }
1623 );
1624
1625 sub user_payments_list {
1626     my($self, $conn, $auth, $user_id, $start_date, $end_date, $order_by) = @_;
1627
1628     my $e = new_editor(authtoken => $auth);
1629     return $e->event unless $e->checkauth;
1630
1631     my $user = $e->retrieve_actor_user($user_id) or return $e->event;
1632     return $e->event unless $e->allowed('VIEW_CIRCULATIONS', $user->home_ou);
1633
1634     $order_by ||= ['payment_ts'];
1635
1636     # all payments by user, between start_date and end_date
1637     my $payments = $e->json_query({
1638         select => {mp => ['id']},
1639         from => {
1640             mp => {
1641                 mbt => {
1642                     fkey => 'xact', field => 'id'}
1643             }
1644         },
1645         where => {
1646             '+mbt' => {usr => $user_id},
1647             '+mp' => {payment_ts => {between => [$start_date, $end_date]}}
1648         },
1649         order_by => {mp => $order_by}
1650     });
1651
1652     for my $payment_id (@$payments) {
1653         my $payment = $e->retrieve_money_payment([
1654             $payment_id->{id},
1655             {
1656                 flesh => 2,
1657                 flesh_fields => {
1658                     mp => [
1659                         'xact',
1660                         'cash_payment',
1661                         'credit_card_payment',
1662                         'credit_payment',
1663                         'check_payment',
1664                         'work_payment',
1665                         'forgive_payment',
1666                         'goods_payment'
1667                     ],
1668                     mbt => [
1669                         'circulation',
1670                         'grocery',
1671                         'reservation'
1672                     ]
1673                 }
1674             }
1675         ]);
1676         $conn->respond($payment);
1677     }
1678
1679     return undef;
1680 }
1681
1682
1683 __PACKAGE__->register_method(
1684         method  => "retrieve_circ_chain",
1685         api_name        => "open-ils.circ.renewal_chain.retrieve_by_circ",
1686     stream => 1,
1687         signature => {
1688         desc => q/Given a circulation, this returns all circulation objects
1689                 that are part of the same chain of renewals./,
1690         params => [
1691             {desc => 'Authentication token', type => 'string'},
1692             {desc => 'Circ ID', type => 'number'},
1693         ],
1694         return => {desc => q/List of circ objects, orderd by oldest circ first/}
1695     }
1696 );
1697
1698 __PACKAGE__->register_method(
1699         method  => "retrieve_circ_chain",
1700         api_name        => "open-ils.circ.renewal_chain.retrieve_by_circ.summary",
1701         signature => {
1702         desc => q/Given a circulation, this returns a summary of the circulation objects
1703                 that are part of the same chain of renewals./,
1704         params => [
1705             {desc => 'Authentication token', type => 'string'},
1706             {desc => 'Circ ID', type => 'number'},
1707         ],
1708         return => {desc => q/Circulation Chain Summary/}
1709     }
1710 );
1711
1712 sub retrieve_circ_chain {
1713     my($self, $conn, $auth, $circ_id) = @_;
1714
1715     my $e = new_editor(authtoken => $auth);
1716     return $e->event unless $e->checkauth;
1717         return $e->event unless $e->allowed('VIEW_CIRCULATIONS');
1718
1719     if($self->api_name =~ /summary/) {
1720         return $U->create_circ_chain_summary($e, $circ_id);
1721
1722     } else {
1723
1724         my $chain = $e->json_query({from => ['action.circ_chain', $circ_id]});
1725
1726         for my $circ_info (@$chain) {
1727             my $circ = Fieldmapper::action::circulation->new;
1728             $circ->$_($circ_info->{$_}) for keys %$circ_info;
1729             $conn->respond($circ);
1730         }
1731     }
1732
1733     return undef;
1734 }
1735
1736 __PACKAGE__->register_method(
1737         method  => "retrieve_prev_circ_chain",
1738         api_name        => "open-ils.circ.prev_renewal_chain.retrieve_by_circ",
1739     stream => 1,
1740         signature => {
1741         desc => q/Given a circulation, this returns all circulation objects
1742                 that are part of the previous chain of renewals./,
1743         params => [
1744             {desc => 'Authentication token', type => 'string'},
1745             {desc => 'Circ ID', type => 'number'},
1746         ],
1747         return => {desc => q/List of circ objects, orderd by oldest circ first/}
1748     }
1749 );
1750
1751 __PACKAGE__->register_method(
1752         method  => "retrieve_prev_circ_chain",
1753         api_name        => "open-ils.circ.prev_renewal_chain.retrieve_by_circ.summary",
1754         signature => {
1755         desc => q/Given a circulation, this returns a summary of the circulation objects
1756                 that are part of the previous chain of renewals./,
1757         params => [
1758             {desc => 'Authentication token', type => 'string'},
1759             {desc => 'Circ ID', type => 'number'},
1760         ],
1761         return => {desc => q/Object containing Circulation Chain Summary and User Id/}
1762     }
1763 );
1764
1765 sub retrieve_prev_circ_chain {
1766     my($self, $conn, $auth, $circ_id) = @_;
1767
1768     my $e = new_editor(authtoken => $auth);
1769     return $e->event unless $e->checkauth;
1770         return $e->event unless $e->allowed('VIEW_CIRCULATIONS');
1771
1772     if($self->api_name =~ /summary/) {
1773         my $first_circ = $e->json_query({from => ['action.circ_chain', $circ_id]})->[0];
1774         my $target_copy = $$first_circ{'target_copy'};
1775         my $usr = $$first_circ{'usr'};
1776         my $last_circ_from_prev_chain = $e->json_query({
1777             'select' => { 'circ' => ['id','usr'] },
1778             'from' => 'circ',
1779             'where' => {
1780                 target_copy => $target_copy,
1781                 xact_start => { '<' => $$first_circ{'xact_start'} }
1782             },
1783             'order_by' => [{ 'class'=>'circ', 'field'=>'xact_start', 'direction'=>'desc' }],
1784             'limit' => 1
1785         })->[0];
1786         return undef unless $last_circ_from_prev_chain;
1787         return undef unless $$last_circ_from_prev_chain{'id'};
1788         my $sum = $e->json_query({from => ['action.summarize_circ_chain', $$last_circ_from_prev_chain{'id'}]})->[0];
1789         return undef unless $sum;
1790         my $obj = Fieldmapper::action::circ_chain_summary->new;
1791         $obj->$_($sum->{$_}) for keys %$sum;
1792         return { 'summary' => $obj, 'usr' => $$last_circ_from_prev_chain{'usr'} };
1793
1794     } else {
1795
1796         my $first_circ = $e->json_query({from => ['action.circ_chain', $circ_id]})->[0];
1797         my $target_copy = $$first_circ{'target_copy'};
1798         my $last_circ_from_prev_chain = $e->json_query({
1799             'select' => { 'circ' => ['id'] },
1800             'from' => 'circ',
1801             'where' => {
1802                 target_copy => $target_copy,
1803                 xact_start => { '<' => $$first_circ{'xact_start'} }
1804             },
1805             'order_by' => [{ 'class'=>'circ', 'field'=>'xact_start', 'direction'=>'desc' }],
1806             'limit' => 1
1807         })->[0];
1808         return undef unless $last_circ_from_prev_chain;
1809         return undef unless $$last_circ_from_prev_chain{'id'};
1810         my $chain = $e->json_query({from => ['action.circ_chain', $$last_circ_from_prev_chain{'id'}]});
1811
1812         for my $circ_info (@$chain) {
1813             my $circ = Fieldmapper::action::circulation->new;
1814             $circ->$_($circ_info->{$_}) for keys %$circ_info;
1815             $conn->respond($circ);
1816         }
1817     }
1818
1819     return undef;
1820 }
1821
1822
1823 __PACKAGE__->register_method(
1824         method  => "get_copy_due_date",
1825         api_name        => "open-ils.circ.copy.due_date.retrieve",
1826         signature => {
1827         desc => q/
1828             Given a copy ID, returns the due date for the copy if it's
1829             currently circulating.  Otherwise, returns null.  Note, this is a public
1830             method requiring no authentication.  Only the due date is exposed.
1831             /,
1832         params => [
1833             {desc => 'Copy ID', type => 'number'}
1834         ],
1835         return => {desc => q/
1836             Due date (ISO date stamp) if the copy is circulating, null otherwise.
1837         /}
1838     }
1839 );
1840
1841 sub get_copy_due_date {
1842     my($self, $conn, $copy_id) = @_;
1843     my $e = new_editor();
1844
1845     my $circ = $e->json_query({
1846         select => {circ => ['due_date']},
1847         from => 'circ',
1848         where => {
1849             target_copy => $copy_id,
1850             checkin_time => undef,
1851             '-or' => [
1852                 {stop_fines => ["MAXFINES","LONGOVERDUE"]},
1853                 {stop_fines => undef}
1854             ],
1855         },
1856         limit => 1
1857     })->[0] or return undef;
1858
1859     return $circ->{due_date};
1860 }
1861
1862
1863
1864
1865
1866 # {"select":{"acp":["id"],"circ":[{"aggregate":true,"transform":"count","alias":"count","column":"id"}]},"from":{"acp":{"circ":{"field":"target_copy","fkey":"id","type":"left"},"acn"{"field":"id","fkey":"call_number"}}},"where":{"+acn":{"record":200057}}
1867
1868
1869 1;