1 package C4
::ILSDI
::Services
;
3 # Copyright 2009 SARL Biblibre
5 # This file is part of Koha.
7 # Koha is free software; you can redistribute it and/or modify it under the
8 # terms of the GNU General Public License as published by the Free Software
9 # Foundation; either version 2 of the License, or (at your option) any later
12 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
13 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
14 # A PARTICULAR PURPOSE. See the GNU General Public License for more details.
16 # You should have received a copy of the GNU General Public License along
17 # with Koha; if not, write to the Free Software Foundation, Inc.,
18 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
29 use C4
::Reserves
qw(AddReserve CancelReserve GetReservesFromBiblionumber GetReservesFromBorrowernumber CanBookBeReserved CanItemBeReserved);
31 use C4
::AuthoritiesMarc
;
32 use C4
::ILSDI
::Utility
;
40 C4::ILS-DI::Services - ILS-DI Services
44 Each function in this module represents an ILS-DI service.
45 They all takes a CGI instance as argument and most of them return a
46 hashref that will be printed by XML::Simple in opac/ilsdi.pl
50 use C4::ILSDI::Services;
56 $out = LookupPatron($cgi);
58 print CGI::header('text/xml');
63 xmldecl => '<?xml version="1.0" encoding="ISO-8859-1" ?>',
64 RootName => 'LookupPatron',
71 =head2 GetAvailability
73 Given a set of biblionumbers or itemnumbers, returns a list with
74 availability of the items associated with the identifiers.
80 list of either biblionumbers or itemnumbers
82 =head3 id_type (Required)
84 defines the type of record identifier being used in the request,
90 =head3 return_type (Optional)
92 requests a particular level of detail in reporting availability,
98 =head3 return_fmt (Optional)
100 requests a particular format or set of formats in reporting
105 sub GetAvailability
{
108 my $out = "<?xml version=\"1.0\" encoding=\"ISO-8859-1\" ?>\n";
109 $out .= "<dlf:collection\n";
110 $out .= " xmlns:dlf=\"http://diglib.org/ilsdi/1.1\"\n";
111 $out .= " xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n";
112 $out .= " xsi:schemaLocation=\"http://diglib.org/ilsdi/1.1\n";
113 $out .= " http://diglib.org/architectures/ilsdi/schemas/1.1/dlfexpanded.xsd\">\n";
115 foreach my $id ( split( / /, $cgi->param('id') ) ) {
116 if ( $cgi->param('id_type') eq "item" ) {
117 my ( $biblionumber, $status, $msg, $location ) = Availability
($id);
119 $out .= " <dlf:record>\n";
120 $out .= " <dlf:bibliographic id=\"" . ( $biblionumber || $id ) . "\" />\n";
121 $out .= " <dlf:items>\n";
122 $out .= " <dlf:item id=\"" . $id . "\">\n";
123 $out .= " <dlf:simpleavailability>\n";
124 $out .= " <dlf:identifier>" . $id . "</dlf:identifier>\n";
125 $out .= " <dlf:availabilitystatus>" . $status . "</dlf:availabilitystatus>\n";
126 if ($msg) { $out .= " <dlf:availabilitymsg>" . $msg . "</dlf:availabilitymsg>\n"; }
127 if ($location) { $out .= " <dlf:location>" . $location . "</dlf:location>\n"; }
128 $out .= " </dlf:simpleavailability>\n";
129 $out .= " </dlf:item>\n";
130 $out .= " </dlf:items>\n";
131 $out .= " </dlf:record>\n";
135 my $biblioitem = ( GetBiblioItemByBiblioNumber
( $id, undef ) )[0];
140 $msg = "Error: could not retrieve availability for this ID";
142 $out .= " <dlf:record>\n";
143 $out .= " <dlf:bibliographic id=\"" . $id . "\" />\n";
144 $out .= " <dlf:simpleavailability>\n";
145 $out .= " <dlf:identifier>" . $id . "</dlf:identifier>\n";
146 $out .= " <dlf:availabilitystatus>" . $status . "</dlf:availabilitystatus>\n";
147 $out .= " <dlf:availabilitymsg>" . $msg . "</dlf:availabilitymsg>\n";
148 $out .= " </dlf:simpleavailability>\n";
149 $out .= " </dlf:record>\n";
152 $out .= "</dlf:collection>\n";
159 Given a list of biblionumbers, returns a list of record objects that
160 contain bibliographic information, as well as associated holdings and item
161 information. The caller may request a specific metadata schema for the
162 record objects to be returned.
164 This function behaves similarly to HarvestBibliographicRecords and
165 HarvestExpandedRecords in Data Aggregation, but allows quick, real time
166 lookup by bibliographic identifier.
168 You can use OAI-PMH ListRecords instead of this service.
173 list of system record identifiers
175 Defines the metadata schema in which the records are returned,
184 # Check if the schema is supported. For now, GetRecords only supports MARCXML
185 if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
186 return { code
=> 'UnsupportedSchema' };
191 # Loop over biblionumbers
192 foreach my $biblionumber ( split( / /, $cgi->param('id') ) ) {
194 # Get the biblioitem from the biblionumber
195 my $biblioitem = ( GetBiblioItemByBiblioNumber
( $biblionumber, undef ) )[0];
196 if ( not $biblioitem->{'biblionumber'} ) {
197 $biblioitem->{code
} = "RecordNotFound";
200 # We don't want MARC to be displayed
201 delete $biblioitem->{'marc'};
203 # Get most of the needed data
204 my $biblioitemnumber = $biblioitem->{'biblioitemnumber'};
205 my @reserves = GetReservesFromBiblionumber
( $biblionumber, undef, undef );
206 my $issues = GetBiblioIssues
($biblionumber);
207 my $items = GetItemsByBiblioitemnumber
($biblioitemnumber);
209 # We loop over the items to clean them
210 foreach my $item (@
$items) {
212 # This hides additionnal XML subfields, we don't need these info
213 delete $item->{'more_subfields_xml'};
215 # Display branch names instead of branch codes
216 $item->{'homebranchname'} = GetBranchName
( $item->{'homebranch'} );
217 $item->{'holdingbranchname'} = GetBranchName
( $item->{'holdingbranch'} );
220 # Hashref building...
221 $biblioitem->{'items'}->{'item'} = $items;
222 $biblioitem->{'reserves'}->{'reserve'} = $reserves[1];
223 $biblioitem->{'issues'}->{'issue'} = $issues;
225 push @records, $biblioitem;
228 return { record
=> \
@records };
231 =head2 GetAuthorityRecords
233 Given a list of authority record identifiers, returns a list of record
234 objects that contain the authority records. The function user may request
235 a specific metadata schema for the record objects.
240 list of authority record identifiers
242 specifies the metadata schema of records to be returned, possible values:
247 sub GetAuthorityRecords
{
250 # If the user asks for an unsupported schema, return an error code
251 if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
252 return { code
=> 'UnsupportedSchema' };
257 # Let's loop over the authority IDs
258 foreach my $authid ( split( / /, $cgi->param('id') ) ) {
260 # Get the record as XML string, or error code
261 push @records, GetAuthorityXML
($authid) || { code
=> 'RecordNotFound' };
264 return { record
=> \
@records };
269 Looks up a patron in the ILS by an identifier, and returns the borrowernumber.
274 an identifier used to look up the patron in Koha
276 the type of the identifier, possible values:
287 # Get the borrower...
288 my $borrower = GetMember
($cgi->param('id_type') => $cgi->param('id'));
289 if ( not $borrower->{'borrowernumber'} ) {
290 return { message
=> 'PatronNotFound' };
294 my $patron->{'id'} = $borrower->{'borrowernumber'};
295 return { code
=> 'PatronNotFound' } unless $$borrower{borrowernumber
};
297 # ...and return his ID
301 =head2 AuthenticatePatron
303 Authenticates a user's login credentials and returns the identifier for
308 - username (Required)
309 user's login identifier
310 - password (Required)
315 sub AuthenticatePatron
{
318 # Check if borrower exists, using a C4::Auth function...
319 unless( C4
::Auth
::checkpw
( C4
::Context
->dbh, $cgi->param('username'), $cgi->param('password') ) ) {
320 return { code
=> 'PatronNotFound' };
324 my $borrower = GetMember
( userid
=> $cgi->param('username') );
327 my $patron->{'id'} = $borrower->{'borrowernumber'};
329 # ... and return his ID
335 Returns specified information about the patron, based on options in the
336 request. This function can optionally return patron's contact information,
337 fine information, hold request information, and loan information.
341 - patron_id (Required)
343 - show_contact (Optional, default 1)
344 whether or not to return patron's contact information in the response
345 - show_fines (Optional, default 0)
346 whether or not to return fine information in the response
347 - show_holds (Optional, default 0)
348 whether or not to return hold request information in the response
349 - show_loans (Optional, default 0)
350 whether or not to return loan information request information in the response
358 my $borrowernumber = $cgi->param('patron_id');
359 my $borrower = GetMemberDetails
( $borrowernumber );
360 return { code
=> 'PatronNotFound' } unless $$borrower{borrowernumber
};
362 # Cleaning the borrower hashref
363 $borrower->{'charges'} = $borrower->{'flags'}->{'CHARGES'}->{'amount'};
364 $borrower->{'branchname'} = GetBranchName
( $borrower->{'branchcode'} );
365 delete $borrower->{'flags'};
366 delete $borrower->{'userid'};
367 delete $borrower->{'password'};
369 # Contact fields management
370 if ( $cgi->param('show_contact') eq "0" ) {
372 # Define contact fields
373 my @contactfields = (
374 'email', 'emailpro', 'fax', 'mobile', 'phone', 'phonepro',
375 'streetnumber', 'zipcode', 'city', 'streettype', 'B_address', 'B_city',
376 'B_email', 'B_phone', 'B_zipcode', 'address', 'address2', 'altcontactaddress1',
377 'altcontactaddress2', 'altcontactaddress3', 'altcontactfirstname', 'altcontactphone', 'altcontactsurname', 'altcontactzipcode'
381 foreach my $field (@contactfields) {
382 delete $borrower->{$field};
387 if ( $cgi->param('show_fines') eq "1" ) {
389 for ( my $i = 1 ; my @charge = getcharges
( $borrowernumber, undef, $i ) ; $i++ ) {
390 push( @charges, @charge );
392 $borrower->{'fines'}->{'fine'} = \
@charges;
395 # Reserves management
396 if ( $cgi->param('show_holds') eq "1" ) {
398 # Get borrower's reserves
399 my @reserves = GetReservesFromBorrowernumber
( $borrowernumber, undef );
400 foreach my $reserve (@reserves) {
402 # Get additional informations
403 my $item = GetBiblioFromItemNumber
( $reserve->{'itemnumber'}, undef );
404 my $branchname = GetBranchName
( $reserve->{'branchcode'} );
406 # Remove unwanted fields
407 delete $item->{'marc'};
408 delete $item->{'marcxml'};
409 delete $item->{'more_subfields_xml'};
411 # Add additional fields
412 $reserve->{'item'} = $item;
413 $reserve->{'branchname'} = $branchname;
414 $reserve->{'title'} = GetBiblio
( $reserve->{'biblionumber'} )->{'title'};
416 $borrower->{'holds'}->{'hold'} = \
@reserves;
420 if ( $cgi->param('show_loans') eq "1" ) {
421 my $issues = GetPendingIssues
($borrowernumber);
422 foreach my $issue ( @
$issues ){
423 $issue->{'issuedate'} = $issue->{'issuedate'}->strftime('%Y-%m-%d %H:%M');
424 $issue->{'date_due'} = $issue->{'date_due'}->strftime('%Y-%m-%d %H:%M');
426 $borrower->{'loans'}->{'loan'} = $issues;
432 =head2 GetPatronStatus
434 Returns a patron's status information.
438 - patron_id (Required)
443 sub GetPatronStatus
{
447 my $borrowernumber = $cgi->param('patron_id');
448 my $borrower = GetMemberDetails
( $borrowernumber );
449 return { code
=> 'PatronNotFound' } unless $$borrower{borrowernumber
};
453 type
=> $$borrower{categorycode
},
455 expiry
=> $$borrower{dateexpiry
},
461 Returns information about the services available on a particular item for
466 - patron_id (Required)
475 # Get the member, or return an error code if not found
476 my $borrowernumber = $cgi->param('patron_id');
477 my $borrower = GetMemberDetails
( $borrowernumber );
478 return { code
=> 'PatronNotFound' } unless $$borrower{borrowernumber
};
480 # Get the item, or return an error code if not found
481 my $itemnumber = $cgi->param('item_id');
482 my $item = GetItem
( $itemnumber );
483 return { code
=> 'RecordNotFound' } unless $$item{itemnumber
};
487 # Reserve level management
488 my $biblionumber = $item->{'biblionumber'};
489 my $canbookbereserved = CanBookBeReserved
( $borrower, $biblionumber );
490 if ($canbookbereserved) {
491 push @availablefor, 'title level hold';
492 my $canitembereserved = IsAvailableForItemLevelRequest
($itemnumber);
493 if ($canitembereserved) {
494 push @availablefor, 'item level hold';
498 # Reserve cancellation management
499 my @reserves = GetReservesFromBorrowernumber
( $borrowernumber, undef );
501 foreach my $reserve (@reserves) {
502 push @reserveditems, $reserve->{'itemnumber'};
504 if ( grep { $itemnumber eq $_ } @reserveditems ) {
505 push @availablefor, 'hold cancellation';
509 my @renewal = CanBookBeRenewed
( $borrowernumber, $itemnumber );
511 push @availablefor, 'loan renewal';
515 my $barcode = $item->{'barcode'} || '';
516 $barcode = barcodedecode
($barcode) if ( $barcode && C4
::Context
->preference('itemBarcodeInputFilter') );
518 my ( $issuingimpossible, $needsconfirmation ) = CanBookBeIssued
( $borrower, $barcode );
520 # TODO push @availablefor, 'loan';
524 $out->{'AvailableFor'} = \
@availablefor;
531 Extends the due date for a borrower's existing issue.
535 - patron_id (Required)
539 - desired_due_date (Required)
540 the date the patron would like the item returned by
547 # Get borrower infos or return an error code
548 my $borrowernumber = $cgi->param('patron_id');
549 my $borrower = GetMemberDetails
( $borrowernumber );
550 return { code
=> 'PatronNotFound' } unless $$borrower{borrowernumber
};
552 # Get the item, or return an error code
553 my $itemnumber = $cgi->param('item_id');
554 my $item = GetItem
( $itemnumber );
555 return { code
=> 'RecordNotFound' } unless $$item{itemnumber
};
557 # Add renewal if possible
558 my @renewal = CanBookBeRenewed
( $borrowernumber, $itemnumber );
559 if ( $renewal[0] ) { AddRenewal
( $borrowernumber, $itemnumber ); }
561 my $issue = GetItemIssue
($itemnumber);
565 $out->{'renewals'} = $issue->{'renewals'};
566 $out->{date_due
} = $issue->{date_due
}->strftime('%Y-%m-%d %H:%S');
567 $out->{'success'} = $renewal[0];
568 $out->{'error'} = $renewal[1];
575 Creates, for a borrower, a biblio-level hold reserve.
579 - patron_id (Required)
583 - request_location (Required)
584 IP address where the end user request is being placed
585 - pickup_location (Optional)
586 a branch code indicating the location to which to deliver the item for pickup
587 - needed_before_date (Optional)
588 date after which hold request is no longer needed
589 - pickup_expiry_date (Optional)
590 date after which item returned to shelf if item is not picked up
597 # Get the borrower or return an error code
598 my $borrowernumber = $cgi->param('patron_id');
599 my $borrower = GetMemberDetails
( $borrowernumber );
600 return { code
=> 'PatronNotFound' } unless $$borrower{borrowernumber
};
602 # Get the biblio record, or return an error code
603 my $biblionumber = $cgi->param('bib_id');
604 my $biblio = GetBiblio
( $biblionumber );
605 return { code
=> 'RecordNotFound' } unless $$biblio{biblionumber
};
607 my $title = $$biblio{title
};
609 # Check if the biblio can be reserved
610 return { code
=> 'NotHoldable' } unless CanBookBeReserved
( $borrowernumber, $biblionumber );
614 # Pickup branch management
615 if ( $cgi->param('pickup_location') ) {
616 $branch = $cgi->param('pickup_location');
617 my $branches = GetBranches
;
618 return { code
=> 'LocationNotFound' } unless $$branches{$branch};
619 } else { # if the request provide no branch, use the borrower's branch
620 $branch = $$borrower{branchcode
};
624 # $branch, $borrowernumber, $biblionumber, $constraint, $bibitems, $priority, $notes, $title, $checkitem, $found
625 AddReserve
( $branch, $borrowernumber, $biblionumber, 'a', undef, 0, undef, $title, undef, undef );
629 $out->{'title'} = $title;
630 $out->{'pickup_location'} = GetBranchName
($branch);
632 # TODO $out->{'date_available'} = '';
639 Creates, for a borrower, an item-level hold request on a specific item of
640 a bibliographic record in Koha.
644 - patron_id (Required)
650 - pickup_location (Optional)
651 a branch code indicating the location to which to deliver the item for pickup
652 - needed_before_date (Optional)
653 date after which hold request is no longer needed
654 - pickup_expiry_date (Optional)
655 date after which item returned to shelf if item is not picked up
662 # Get the borrower or return an error code
663 my $borrowernumber = $cgi->param('patron_id');
664 my $borrower = GetMemberDetails
( $borrowernumber );
665 return { code
=> 'PatronNotFound' } unless $$borrower{borrowernumber
};
667 # Get the biblio or return an error code
668 my $biblionumber = $cgi->param('bib_id');
669 my $biblio = GetBiblio
($biblionumber);
670 return { code
=> 'RecordNotFound' } unless $$biblio{biblionumber
};
672 my $title = $$biblio{title
};
674 # Get the item or return an error code
675 my $itemnumber = $cgi->param('item_id');
676 my $item = GetItem
( $itemnumber );
677 return { code
=> 'RecordNotFound' } unless $$item{itemnumber
};
679 # If the biblio does not match the item, return an error code
680 return { code
=> 'RecordNotFound' } if $$item{biblionumber
} ne $$biblio{biblionumber
};
682 # Check for item disponibility
683 my $canitembereserved = C4
::Reserves
::CanItemBeReserved
( $borrowernumber, $itemnumber );
684 my $canbookbereserved = C4
::Reserves
::CanBookBeReserved
( $borrowernumber, $biblionumber );
685 return { code
=> 'NotHoldable' } unless $canbookbereserved and $canitembereserved;
689 # Pickup branch management
690 if ( $cgi->param('pickup_location') ) {
691 $branch = $cgi->param('pickup_location');
692 my $branches = GetBranches
();
693 return { code
=> 'LocationNotFound' } unless $$branches{$branch};
694 } else { # if the request provide no branch, use the borrower's branch
695 $branch = $$borrower{branchcode
};
702 $rank = '0' unless C4
::Context
->preference('ReservesNeedReturns');
703 if ( $item->{'holdingbranch'} eq $branch ) {
704 $found = 'W' unless C4
::Context
->preference('ReservesNeedReturns');
708 # $branch,$borrowernumber,$biblionumber,$constraint,$bibitems,$priority,$resdate,$expdate,$notes,$title,$checkitem,$found
709 AddReserve
( $branch, $borrowernumber, $biblionumber, 'a', undef, $rank, '', '', '', $title, $itemnumber, $found );
713 $out->{'pickup_location'} = GetBranchName
($branch);
715 # TODO $out->{'date_available'} = '';
722 Cancels an active reserve request for the borrower.
726 - patron_id (Required)
736 # Get the borrower or return an error code
737 my $borrowernumber = $cgi->param('patron_id');
738 my $borrower = GetMemberDetails
( $borrowernumber );
739 return { code
=> 'PatronNotFound' } unless $$borrower{borrowernumber
};
741 # Get the item or return an error code
742 my $itemnumber = $cgi->param('item_id');
743 my $item = GetItem
( $itemnumber );
744 return { code
=> 'RecordNotFound' } unless $$item{itemnumber
};
746 # Get borrower's reserves
747 my @reserves = GetReservesFromBorrowernumber
( $borrowernumber, undef );
750 # ...and loop over it to build an array of reserved itemnumbers
751 foreach my $reserve (@reserves) {
752 push @reserveditems, $reserve->{'itemnumber'};
755 # if the item was not reserved by the borrower, returns an error code
756 return { code
=> 'NotCanceled' } unless any
{ $itemnumber eq $_ } @reserveditems;
759 CancelReserve
( $itemnumber, undef, $borrowernumber );
761 return { code
=> 'Canceled' };