1 # ---------------------------------------------------------------
2 # Copyright (C) 2005 Georgia Public Library Service
3 # Bill Erickson <highfalutin@gmail.com>
5 # This program is free software; you can redistribute it and/or
6 # modify it under the terms of the GNU General Public License
7 # as published by the Free Software Foundation; either version 2
8 # of the License, or (at your option) any later version.
10 # This program is distributed in the hope that it will be useful,
11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 # GNU General Public License for more details.
14 # ---------------------------------------------------------------
17 package OpenILS::Application::Circ::Holds;
18 use base qw/OpenSRF::Application/;
19 use strict; use warnings;
20 use OpenILS::Application::AppUtils;
22 use OpenSRF::EX qw(:try);
25 use OpenSRF::Utils::Logger qw(:logger);
27 my $apputils = "OpenILS::Application::AppUtils";
31 __PACKAGE__->register_method(
32 method => "create_hold",
33 api_name => "open-ils.circ.holds.create",
35 Create a new hold for an item. From a permissions perspective,
36 the login session is used as the 'requestor' of the hold.
37 The hold recipient is determined by the 'usr' setting within
40 First we verify the requestion has holds request permissions.
41 Then we verify that the recipient is allowed to make the given hold.
42 If not, we see if the requestor has "override" capabilities. If not,
43 a permission exception is returned. If permissions allow, we cycle
44 through the set of holds objects and create.
46 If the recipient does not have permission to place multiple holds
47 on a single title and said operation is attempted, a permission
52 my( $self, $client, $login_session, @holds) = @_;
54 if(!@holds){return 0;}
55 my( $user, $evt ) = $apputils->checkses($login_session);
59 if(ref($holds[0]) eq 'ARRAY') {
61 } else { $holds = [ @holds ]; }
63 $logger->debug("Iterating over holds requests...");
65 for my $hold (@$holds) {
68 my $type = $hold->hold_type;
70 $logger->activity("User " . $user->id .
71 " creating new hold of type $type for user " . $hold->usr);
74 if($user->id ne $hold->usr) {
75 ( $recipient, $evt ) = $apputils->fetch_user($hold->usr);
85 # am I allowed to place holds for this user?
86 if($hold->requestor ne $hold->usr) {
87 $perm = _check_request_holds_perm($user->id, $user->home_ou);
88 if($perm) { return $perm; }
91 # is this user allowed to have holds of this type?
92 $perm = _check_holds_perm($type, $hold->usr, $recipient->home_ou);
94 #if there is a requestor, see if the requestor has override privelages
95 if($hold->requestor ne $hold->usr) {
96 $perm = _check_request_holds_override($user->id, $user->home_ou);
97 if($perm) {return $perm;}
104 #enforce the fact that the login is the one requesting the hold
105 $hold->requestor($user->id);
107 my $resp = $apputils->simplereq(
109 'open-ils.storage.direct.action.hold_request.create', $hold );
112 return OpenSRF::EX::ERROR ("Error creating hold");
119 # makes sure that a user has permission to place the type of requested hold
120 # returns the Perm exception if not allowed, returns undef if all is well
121 sub _check_holds_perm {
122 my($type, $user_id, $org_id) = @_;
126 if($evt = $apputils->check_perms(
127 $user_id, $org_id, "MR_HOLDS")) {
131 } elsif ($type eq "T") {
132 if($evt = $apputils->check_perms(
133 $user_id, $org_id, "TITLE_HOLDS")) {
137 } elsif($type eq "V") {
138 if($evt = $apputils->check_perms(
139 $user_id, $org_id, "VOLUME_HOLDS")) {
143 } elsif($type eq "C") {
144 if($evt = $apputils->check_perms(
145 $user_id, $org_id, "COPY_HOLDS")) {
153 # tests if the given user is allowed to place holds on another's behalf
154 sub _check_request_holds_perm {
157 if(my $evt = $apputils->check_perms(
158 $user_id, $org_id, "REQUEST_HOLDS")) {
163 sub _check_request_holds_override {
166 if(my $evt = $apputils->check_perms(
167 $user_id, $org_id, "REQUEST_HOLDS_OVERRIDE")) {
173 __PACKAGE__->register_method(
174 method => "retrieve_holds",
175 api_name => "open-ils.circ.holds.retrieve",
177 Retrieves all the holds for the specified user id. The login session
178 is the requestor and if the requestor is different from the user, then
179 the requestor must have VIEW_HOLDS permissions.
184 my($self, $client, $login_session, $user_id) = @_;
186 my( $user, $target, $evt ) = $apputils->checkses_requestor(
187 $login_session, $user_id, 'VIEW_HOLDS' );
190 return $apputils->simplereq(
192 "open-ils.storage.direct.action.hold_request.search.atomic",
193 "usr" => $user_id , fulfillment_time => undef, { order_by => "request_time" });
197 __PACKAGE__->register_method(
198 method => "cancel_hold",
199 api_name => "open-ils.circ.hold.cancel",
201 Cancels the specified hold. The login session
202 is the requestor and if the requestor is different from the usr field
203 on the hold, the requestor must have CANCEL_HOLDS permissions.
204 the hold may be either the hold object or the hold id
208 my($self, $client, $login_session, $holdid) = @_;
211 my $user = $apputils->check_user_session($login_session);
212 my( $hold, $evt ) = $apputils->fetch_hold($holdid);
215 if($user->id ne $hold->usr) { #am I allowed to cancel this user's hold?
216 if($evt = $apputils->checkperms(
217 $user->id, $user->home_ou, 'CANCEL_HOLDS')) {
222 $logger->activity( "User " . $user->id .
223 " canceling hold $holdid for user " . $hold->user );
225 return $apputils->simplereq(
227 "open-ils.storage.direct.action.hold_request.delete", $hold );
231 __PACKAGE__->register_method(
232 method => "update_hold",
233 api_name => "open-ils.circ.hold.update",
235 Updates the specified hold. The login session
236 is the requestor and if the requestor is different from the usr field
237 on the hold, the requestor must have UPDATE_HOLDS permissions.
241 my($self, $client, $login_session, $hold) = @_;
243 my( $requestor, $target, $evt ) = $apputils->checkses_requestor(
244 $login_session, $hold->usr, 'UPDATE_HOLD' );
247 $logger->activity('User ' + $requestor->id .
248 ' updating hold ' . $hold->id . ' for user ' . $target->id );
251 return $apputils->simplereq(
253 "open-ils.storage.direct.action.hold_request.update", $hold );
257 __PACKAGE__->register_method(
258 method => "retrieve_hold_status",
259 api_name => "open-ils.circ.hold.status.retrieve",
261 Calculates the current status of the hold.
262 the requestor must have VIEW_HOLDS permissions if the hold is for a user
263 other than the requestor.
264 Returns -1 on error (for now)
265 Returns 1 for 'waiting for copy to become available'
266 Returns 2 for 'waiting for copy capture'
267 Returns 3 for 'in transit'
268 Returns 4 for 'arrived'
271 sub retrieve_hold_status {
272 my($self, $client, $login_session, $hold_id) = @_;
275 my( $requestor, $target, $hold, $copy, $transit, $evt );
277 ( $hold, $evt ) = $apputils->fetch_hold($hold_id);
280 ( $requestor, $target, $evt ) = $apputils->checkses_requestor(
281 $login_session, $hold->usr, 'VIEW_HOLD' );
284 return 1 unless (defined($hold->current_copy));
286 ( $copy, $evt ) = $apputils->fetch_copy($hold->current_copy);
289 return 4 if ($hold->capture_time and $copy->circ_lib eq $hold->pickup_lib);
291 ( $transit, $evt ) = $apputils->fetch_hold_transit_by_hold( $hold->id );
292 return 4 if(ref($transit) and defined($transit->dest_recv_time) );
294 return 3 if defined($hold->capture_time);
299 __PACKAGE__->register_method(
300 method => "capture_copy",
301 api_name => "open-ils.circ.hold.capture_copy.barcode",
303 Captures a copy to fulfil a hold
304 Params is login session and copy barcode
305 Optional param is 'flesh'. If set, we also return the
306 relevant copy and title
307 login mus have COPY_CHECKIN permissions (since this is essentially
312 my( $self, $client, $login_session, $barcode, $flesh ) = @_;
314 my( $user, $target, $copy, $hold, $evt );
316 ( $user, $evt ) = $apputils->checkses($login_session);
319 # am I allowed to checkin a copy?
320 $evt = $apputils->check_perms($user->id, $user->home_ou, "COPY_CHECKIN");
323 $logger->info("Capturing copy with barcode $barcode, flesh=$flesh");
325 my $session = $apputils->start_db_session();
327 ($copy, $evt) = $apputils->fetch_copy_by_barcode($barcode);
330 $logger->debug("Capturing copy " . $copy->id);
332 ( $hold, $evt ) = _find_local_hold_for_copy($session, $copy, $user);
335 warn "Found hold " . $hold->id . "\n";
336 $logger->info("We found a hold " .$hold->id. "for capturing copy with barcode $barcode");
338 $hold->current_copy($copy->id);
339 $hold->capture_time("now");
342 my $stat = $session->request(
343 "open-ils.storage.direct.action.hold_request.update", $hold)->gather(1);
344 if(!$stat) { throw OpenSRF::EX::ERROR
345 ("Error updating hold request " . $copy->id); }
347 $copy->status(8); #status on holds shelf
349 # if the staff member capturing this item is not at the pickup lib
350 if( $user->home_ou ne $hold->pickup_lib ) {
351 $self->_build_hold_transit( $login_session, $session, $hold, $user, $copy );
354 $copy->editor($user->id);
355 $copy->edit_date("now");
356 $stat = $session->request(
357 "open-ils.storage.direct.asset.copy.update", $copy )->gather(1);
358 if(!$stat) { throw OpenSRF::EX ("Error updating copy " . $copy->id); }
363 ($title, $evt) = $apputils->fetch_record_by_copy( $copy->id );
365 $title = $apputils->record_to_mvr($title);
368 $apputils->commit_db_session($session);
372 route_to => $hold->pickup_lib,
377 return OpenILS::Event->new('SUCCESS', payload => $payload );
380 sub _build_hold_transit {
381 my( $self, $login_session, $session, $hold, $user, $copy ) = @_;
382 my $trans = Fieldmapper::action::hold_transit_copy->new;
384 $trans->hold($hold->id);
385 $trans->source($user->home_ou);
386 $trans->dest($hold->pickup_lib);
387 $trans->source_send_time("now");
388 $trans->target_copy($copy->id);
389 $trans->copy_status($copy->status);
391 my $meth = $self->method_lookup("open-ils.circ.hold_transit.create");
392 my ($stat) = $meth->run( $login_session, $trans, $session );
393 if(!$stat) { throw OpenSRF::EX ("Error creating new hold transit"); }
394 else { $copy->status(6); } #status in transit
398 sub _find_local_hold_for_copy {
403 my $evt = OpenILS::Event->new('HOLD_NOT_FOUND');
405 # first see if this copy has already been selected to fulfill a hold
406 my $hold = $session->request(
407 "open-ils.storage.direct.action.hold_request.search_where",
408 { current_copy => $copy->id, capture_time => undef } )->gather(1);
410 $logger->debug("Hold found for copy " . $copy->id);
412 if($hold) {return $hold;}
414 $logger->debug("searching for local hold at org " .
415 $user->home_ou . " and copy " . $copy->id);
417 my $holdid = $session->request(
418 "open-ils.storage.action.hold_request.nearest_hold",
419 $user->home_ou, $copy->id )->gather(1);
421 return (undef, $evt) unless defined $holdid;
423 $logger->debug("Found hold id $holdid while ".
424 "searching nearest hold to " .$user->home_ou);
426 return $apputils->fetch_hold($holdid);
430 __PACKAGE__->register_method(
431 method => "create_hold_transit",
432 api_name => "open-ils.circ.hold_transit.create",
434 Creates a new transit object
437 sub create_hold_transit {
438 my( $self, $client, $login_session, $transit, $session ) = @_;
440 my( $user, $evt ) = $apputils->checkses($login_session);
442 $evt = $apputils->check_perms($user->id, $user->home_ou, "CREATE_TRANSIT");
446 if($session) { $ses = $session; }
447 else { $ses = OpenSRF::AppSession->create("open-ils.storage"); }
449 return $ses->request(
450 "open-ils.storage.direct.action.hold_transit_copy.create", $transit )->gather(1);