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