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