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