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;