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
8 # under the terms of the GNU General Public License as published by
9 # the Free Software Foundation; either version 3 of the License, or
10 # (at your option) any later version.
12 # Koha is distributed in the hope that it will be useful, but
13 # WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 # GNU General Public License for more details.
17 # You should have received a copy of the GNU General Public License
18 # along with Koha; if not, see <http://www.gnu.org/licenses>.
28 use C4::Reserves qw(AddReserve GetReservesFromBiblionumber GetReservesFromBorrowernumber CanBookBeReserved CanItemBeReserved IsAvailableForItemLevelRequest);
30 use C4::AuthoritiesMarc;
36 use C4::Members::Attributes qw(GetBorrowerAttributes);
42 C4::ILS-DI::Services - ILS-DI Services
46 Each function in this module represents an ILS-DI service.
47 They all takes a CGI instance as argument and most of them return a
48 hashref that will be printed by XML::Simple in opac/ilsdi.pl
52 use C4::ILSDI::Services;
58 $out = LookupPatron($cgi);
60 print CGI::header('text/xml');
65 xmldecl => '<?xml version="1.0" encoding="UTF-8" ?>',
66 RootName => 'LookupPatron',
73 =head2 GetAvailability
75 Given a set of biblionumbers or itemnumbers, returns a list with
76 availability of the items associated with the identifiers.
82 list of either biblionumbers or itemnumbers
84 =head3 id_type (Required)
86 defines the type of record identifier being used in the request,
92 =head3 return_type (Optional)
94 requests a particular level of detail in reporting availability,
100 =head3 return_fmt (Optional)
102 requests a particular format or set of formats in reporting
107 sub GetAvailability {
110 my $out = "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n";
111 $out .= "<dlf:collection\n";
112 $out .= " xmlns:dlf=\"http://diglib.org/ilsdi/1.1\"\n";
113 $out .= " xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n";
114 $out .= " xsi:schemaLocation=\"http://diglib.org/ilsdi/1.1\n";
115 $out .= " http://diglib.org/architectures/ilsdi/schemas/1.1/dlfexpanded.xsd\">\n";
117 foreach my $id ( split( / /, $cgi->param('id') ) ) {
118 if ( $cgi->param('id_type') eq "item" ) {
119 my ( $biblionumber, $status, $msg, $location ) = _availability($id);
121 $out .= " <dlf:record>\n";
122 $out .= " <dlf:bibliographic id=\"" . ( $biblionumber || $id ) . "\" />\n";
123 $out .= " <dlf:items>\n";
124 $out .= " <dlf:item id=\"" . $id . "\">\n";
125 $out .= " <dlf:simpleavailability>\n";
126 $out .= " <dlf:identifier>" . $id . "</dlf:identifier>\n";
127 $out .= " <dlf:availabilitystatus>" . $status . "</dlf:availabilitystatus>\n";
128 if ($msg) { $out .= " <dlf:availabilitymsg>" . $msg . "</dlf:availabilitymsg>\n"; }
129 if ($location) { $out .= " <dlf:location>" . $location . "</dlf:location>\n"; }
130 $out .= " </dlf:simpleavailability>\n";
131 $out .= " </dlf:item>\n";
132 $out .= " </dlf:items>\n";
133 $out .= " </dlf:record>\n";
137 my $biblioitem = ( GetBiblioItemByBiblioNumber( $id, undef ) )[0];
142 $msg = "Error: could not retrieve availability for this ID";
144 $out .= " <dlf:record>\n";
145 $out .= " <dlf:bibliographic id=\"" . $id . "\" />\n";
146 $out .= " <dlf:simpleavailability>\n";
147 $out .= " <dlf:identifier>" . $id . "</dlf:identifier>\n";
148 $out .= " <dlf:availabilitystatus>" . $status . "</dlf:availabilitystatus>\n";
149 $out .= " <dlf:availabilitymsg>" . $msg . "</dlf:availabilitymsg>\n";
150 $out .= " </dlf:simpleavailability>\n";
151 $out .= " </dlf:record>\n";
154 $out .= "</dlf:collection>\n";
161 Given a list of biblionumbers, returns a list of record objects that
162 contain bibliographic information, as well as associated holdings and item
163 information. The caller may request a specific metadata schema for the
164 record objects to be returned.
166 This function behaves similarly to HarvestBibliographicRecords and
167 HarvestExpandedRecords in Data Aggregation, but allows quick, real time
168 lookup by bibliographic identifier.
170 You can use OAI-PMH ListRecords instead of this service.
175 list of system record identifiers
177 Defines the metadata schema in which the records are returned,
186 # Check if the schema is supported. For now, GetRecords only supports MARCXML
187 if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
188 return { code => 'UnsupportedSchema' };
193 # Loop over biblionumbers
194 foreach my $biblionumber ( split( / /, $cgi->param('id') ) ) {
196 # Get the biblioitem from the biblionumber
197 my $biblioitem = ( GetBiblioItemByBiblioNumber( $biblionumber, undef ) )[0];
198 if ( not $biblioitem->{'biblionumber'} ) {
199 $biblioitem->{code} = "RecordNotFound";
203 my $record = GetMarcBiblio($biblionumber, $embed_items);
205 $biblioitem->{marcxml} = $record->as_xml_record();
208 # We don't want MARC to be displayed
209 delete $biblioitem->{'marc'};
211 # Get most of the needed data
212 my $biblioitemnumber = $biblioitem->{'biblioitemnumber'};
213 my $reserves = GetReservesFromBiblionumber({ biblionumber => $biblionumber });
214 my $issues = GetBiblioIssues($biblionumber);
215 my $items = GetItemsByBiblioitemnumber($biblioitemnumber);
217 # We loop over the items to clean them
218 foreach my $item (@$items) {
220 # This hides additionnal XML subfields, we don't need these info
221 delete $item->{'more_subfields_xml'};
223 # Display branch names instead of branch codes
224 my $home_library = Koha::Libraries->find( $item->{homebranch} );
225 my $holding_library = Koha::Libraries->find( $item->{holdingbranch} );
226 $item->{'homebranchname'} = $home_library ? $home_library->branchname : '';
227 $item->{'holdingbranchname'} = $holding_library ? $holding_library->branchname : '';
230 # Hashref building...
231 $biblioitem->{'items'}->{'item'} = $items;
232 $biblioitem->{'reserves'}->{'reserve'} = $reserves;
233 $biblioitem->{'issues'}->{'issue'} = $issues;
235 push @records, $biblioitem;
238 return { record => \@records };
241 =head2 GetAuthorityRecords
243 Given a list of authority record identifiers, returns a list of record
244 objects that contain the authority records. The function user may request
245 a specific metadata schema for the record objects.
250 list of authority record identifiers
252 specifies the metadata schema of records to be returned, possible values:
257 sub GetAuthorityRecords {
260 # If the user asks for an unsupported schema, return an error code
261 if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
262 return { code => 'UnsupportedSchema' };
267 # Let's loop over the authority IDs
268 foreach my $authid ( split( / /, $cgi->param('id') ) ) {
270 # Get the record as XML string, or error code
271 push @records, GetAuthorityXML($authid) || { code => 'RecordNotFound' };
274 return { record => \@records };
279 Looks up a patron in the ILS by an identifier, and returns the borrowernumber.
284 an identifier used to look up the patron in Koha
286 the type of the identifier, possible values:
297 # Get the borrower...
298 my $borrower = GetMember($cgi->param('id_type') => $cgi->param('id'));
299 if ( not $borrower->{'borrowernumber'} ) {
300 return { message => 'PatronNotFound' };
304 my $patron->{'id'} = $borrower->{'borrowernumber'};
305 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
307 # ...and return his ID
311 =head2 AuthenticatePatron
313 Authenticates a user's login credentials and returns the identifier for
318 - username (Required)
319 user's login identifier (userid or cardnumber)
320 - password (Required)
325 sub AuthenticatePatron {
327 my $username = $cgi->param('username');
328 my $password = $cgi->param('password');
329 my ($status, $cardnumber, $userid) = C4::Auth::checkpw( C4::Context->dbh, $username, $password );
332 my $borrower = GetMember( cardnumber => $cardnumber );
333 my $patron->{'id'} = $borrower->{'borrowernumber'};
337 return { code => 'PatronNotFound' };
343 Returns specified information about the patron, based on options in the
344 request. This function can optionally return patron's contact information,
345 fine information, hold request information, and loan information.
349 - patron_id (Required)
351 - show_contact (Optional, default 1)
352 whether or not to return patron's contact information in the response
353 - show_fines (Optional, default 0)
354 whether or not to return fine information in the response
355 - show_holds (Optional, default 0)
356 whether or not to return hold request information in the response
357 - show_loans (Optional, default 0)
358 whether or not to return loan information request information in the response
366 my $borrowernumber = $cgi->param('patron_id');
367 my $borrower = GetMemberDetails( $borrowernumber );
368 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
370 # Cleaning the borrower hashref
371 $borrower->{'charges'} = $borrower->{'flags'}->{'CHARGES'}->{'amount'};
372 my $library = Koha::Libraries->find( $borrower->{branchcode} );
373 $borrower->{'branchname'} = $library ? $library->branchname : '';
374 delete $borrower->{'flags'};
375 delete $borrower->{'userid'};
376 delete $borrower->{'password'};
378 # Contact fields management
379 if ( defined $cgi->param('show_contact') && $cgi->param('show_contact') eq "0" ) {
381 # Define contact fields
382 my @contactfields = (
383 'email', 'emailpro', 'fax', 'mobile', 'phone', 'phonepro',
384 'streetnumber', 'zipcode', 'city', 'streettype', 'B_address', 'B_city',
385 'B_email', 'B_phone', 'B_zipcode', 'address', 'address2', 'altcontactaddress1',
386 'altcontactaddress2', 'altcontactaddress3', 'altcontactfirstname', 'altcontactphone', 'altcontactsurname', 'altcontactzipcode'
390 foreach my $field (@contactfields) {
391 delete $borrower->{$field};
396 if ( $cgi->param('show_fines') && $cgi->param('show_fines') eq "1" ) {
398 for ( my $i = 1 ; my @charge = getcharges( $borrowernumber, undef, $i ) ; $i++ ) {
399 push( @charges, @charge );
401 $borrower->{'fines'}->{'fine'} = \@charges;
404 # Reserves management
405 if ( $cgi->param('show_holds') && $cgi->param('show_holds') eq "1" ) {
407 # Get borrower's reserves
408 my @reserves = GetReservesFromBorrowernumber( $borrowernumber, undef );
409 foreach my $reserve (@reserves) {
411 # Get additional informations
412 my $item = GetBiblioFromItemNumber( $reserve->{'itemnumber'}, undef );
413 my $library = Koha::Libraries->find( $reserve->{branchcode} );
414 my $branchname = $library ? $library->branchname : '';
416 # Remove unwanted fields
417 delete $item->{'marc'};
418 delete $item->{'marcxml'};
419 delete $item->{'more_subfields_xml'};
421 # Add additional fields
422 $reserve->{'item'} = $item;
423 $reserve->{'branchname'} = $branchname;
424 $reserve->{'title'} = GetBiblio( $reserve->{'biblionumber'} )->{'title'};
426 $borrower->{'holds'}->{'hold'} = \@reserves;
430 if ( $cgi->param('show_loans') && $cgi->param('show_loans') eq "1" ) {
431 my $issues = GetPendingIssues($borrowernumber);
432 foreach my $issue ( @$issues ){
433 $issue->{'issuedate'} = $issue->{'issuedate'}->strftime('%Y-%m-%d %H:%M');
434 $issue->{'date_due'} = $issue->{'date_due'}->strftime('%Y-%m-%d %H:%M');
436 $borrower->{'loans'}->{'loan'} = $issues;
439 if ( $cgi->param('show_attributes') eq "1" ) {
440 my $attrs = GetBorrowerAttributes( $borrowernumber, 0, 1 );
441 $borrower->{'attributes'} = $attrs;
447 =head2 GetPatronStatus
449 Returns a patron's status information.
453 - patron_id (Required)
458 sub GetPatronStatus {
462 my $borrowernumber = $cgi->param('patron_id');
463 my $borrower = GetMemberDetails( $borrowernumber );
464 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
468 type => $$borrower{categorycode},
470 expiry => $$borrower{dateexpiry},
476 Returns information about the services available on a particular item for
481 - patron_id (Required)
490 # Get the member, or return an error code if not found
491 my $borrowernumber = $cgi->param('patron_id');
492 my $borrower = GetMemberDetails( $borrowernumber );
493 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
495 # Get the item, or return an error code if not found
496 my $itemnumber = $cgi->param('item_id');
497 my $item = GetItem( $itemnumber );
498 return { code => 'RecordNotFound' } unless $$item{itemnumber};
502 # Reserve level management
503 my $biblionumber = $item->{'biblionumber'};
504 my $canbookbereserved = CanBookBeReserved( $borrower, $biblionumber );
505 if ($canbookbereserved eq 'OK') {
506 push @availablefor, 'title level hold';
507 my $canitembereserved = IsAvailableForItemLevelRequest($item, $borrower);
508 if ($canitembereserved) {
509 push @availablefor, 'item level hold';
513 # Reserve cancellation management
514 my @reserves = GetReservesFromBorrowernumber( $borrowernumber, undef );
516 foreach my $reserve (@reserves) {
517 push @reserveditems, $reserve->{'itemnumber'};
519 if ( grep { $itemnumber eq $_ } @reserveditems ) {
520 push @availablefor, 'hold cancellation';
524 my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
526 push @availablefor, 'loan renewal';
530 my $barcode = $item->{'barcode'} || '';
531 $barcode = barcodedecode($barcode) if ( $barcode && C4::Context->preference('itemBarcodeInputFilter') );
533 my ( $issuingimpossible, $needsconfirmation ) = CanBookBeIssued( $borrower, $barcode );
535 # TODO push @availablefor, 'loan';
539 $out->{'AvailableFor'} = \@availablefor;
546 Extends the due date for a borrower's existing issue.
550 - patron_id (Required)
554 - desired_due_date (Required)
555 the date the patron would like the item returned by
562 # Get borrower infos or return an error code
563 my $borrowernumber = $cgi->param('patron_id');
564 my $borrower = GetMemberDetails( $borrowernumber );
565 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
567 # Get the item, or return an error code
568 my $itemnumber = $cgi->param('item_id');
569 my $item = GetItem( $itemnumber );
570 return { code => 'RecordNotFound' } unless $$item{itemnumber};
572 # Add renewal if possible
573 my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
574 if ( $renewal[0] ) { AddRenewal( $borrowernumber, $itemnumber ); }
576 my $issue = GetItemIssue($itemnumber);
580 $out->{'renewals'} = $issue->{'renewals'};
581 $out->{date_due} = $issue->{date_due}->strftime('%Y-%m-%d %H:%S');
582 $out->{'success'} = $renewal[0];
583 $out->{'error'} = $renewal[1];
590 Creates, for a borrower, a biblio-level hold reserve.
594 - patron_id (Required)
598 - request_location (Required)
599 IP address where the end user request is being placed
600 - pickup_location (Optional)
601 a branch code indicating the location to which to deliver the item for pickup
602 - needed_before_date (Optional)
603 date after which hold request is no longer needed
604 - pickup_expiry_date (Optional)
605 date after which item returned to shelf if item is not picked up
612 # Get the borrower or return an error code
613 my $borrowernumber = $cgi->param('patron_id');
614 my $borrower = GetMemberDetails( $borrowernumber );
615 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
617 # Get the biblio record, or return an error code
618 my $biblionumber = $cgi->param('bib_id');
619 my $biblio = GetBiblio( $biblionumber );
620 return { code => 'RecordNotFound' } unless $$biblio{biblionumber};
622 my $title = $$biblio{title};
624 # Check if the biblio can be reserved
625 return { code => 'NotHoldable' } unless CanBookBeReserved( $borrowernumber, $biblionumber ) eq 'OK';
629 # Pickup branch management
630 if ( $cgi->param('pickup_location') ) {
631 $branch = $cgi->param('pickup_location');
632 return { code => 'LocationNotFound' } unless Koha::Libraries->find($branch);
633 } else { # if the request provide no branch, use the borrower's branch
634 $branch = $$borrower{branchcode};
638 # $branch, $borrowernumber, $biblionumber,
639 # $constraint, $bibitems, $priority, $resdate, $expdate, $notes,
640 # $title, $checkitem, $found
641 my $priority= C4::Reserves::CalculatePriority( $biblionumber );
642 AddReserve( $branch, $borrowernumber, $biblionumber, undef, $priority, undef, undef, undef, $title, undef, undef );
646 $out->{'title'} = $title;
647 my $library = Koha::Libraries->find( $branch );
648 $out->{'pickup_location'} = $library ? $library->branchname : '';
650 # TODO $out->{'date_available'} = '';
657 Creates, for a borrower, an item-level hold request on a specific item of
658 a bibliographic record in Koha.
662 - patron_id (Required)
668 - pickup_location (Optional)
669 a branch code indicating the location to which to deliver the item for pickup
670 - needed_before_date (Optional)
671 date after which hold request is no longer needed
672 - pickup_expiry_date (Optional)
673 date after which item returned to shelf if item is not picked up
680 # Get the borrower or return an error code
681 my $borrowernumber = $cgi->param('patron_id');
682 my $borrower = GetMemberDetails( $borrowernumber );
683 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
685 # Get the biblio or return an error code
686 my $biblionumber = $cgi->param('bib_id');
687 my $biblio = GetBiblio($biblionumber);
688 return { code => 'RecordNotFound' } unless $$biblio{biblionumber};
690 my $title = $$biblio{title};
692 # Get the item or return an error code
693 my $itemnumber = $cgi->param('item_id');
694 my $item = GetItem( $itemnumber );
695 return { code => 'RecordNotFound' } unless $$item{itemnumber};
697 # If the biblio does not match the item, return an error code
698 return { code => 'RecordNotFound' } if $$item{biblionumber} ne $$biblio{biblionumber};
700 # Check for item disponibility
701 my $canitembereserved = C4::Reserves::CanItemBeReserved( $borrowernumber, $itemnumber );
702 my $canbookbereserved = C4::Reserves::CanBookBeReserved( $borrowernumber, $biblionumber );
703 return { code => 'NotHoldable' } unless $canbookbereserved eq 'OK' and $canitembereserved eq 'OK';
705 # Pickup branch management
707 if ( $cgi->param('pickup_location') ) {
708 $branch = $cgi->param('pickup_location');
709 return { code => 'LocationNotFound' } unless Koha::Libraries->find($branch);
710 } else { # if the request provide no branch, use the borrower's branch
711 $branch = $$borrower{branchcode};
715 # $branch, $borrowernumber, $biblionumber,
716 # $constraint, $bibitems, $priority, $resdate, $expdate, $notes,
717 # $title, $checkitem, $found
718 my $priority= C4::Reserves::CalculatePriority( $biblionumber );
719 AddReserve( $branch, $borrowernumber, $biblionumber, undef, $priority, undef, undef, undef, $title, $itemnumber, undef );
723 my $library = Koha::Libraries->find( $branch );
724 $out->{'pickup_location'} = $library ? $library->branchname : '';
726 # TODO $out->{'date_available'} = '';
733 Cancels an active reserve request for the borrower.
737 - patron_id (Required)
747 # Get the borrower or return an error code
748 my $borrowernumber = $cgi->param('patron_id');
749 my $borrower = GetMemberDetails( $borrowernumber );
750 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
752 # Get the reserve or return an error code
753 my $reserve_id = $cgi->param('item_id');
754 my $reserve = C4::Reserves::GetReserve($reserve_id);
755 return { code => 'RecordNotFound' } unless $reserve;
756 return { code => 'RecordNotFound' } unless ($reserve->{borrowernumber} == $borrowernumber);
758 C4::Reserves::CancelReserve({reserve_id => $reserve_id});
760 return { code => 'Canceled' };
765 Returns, for an itemnumber, an array containing availability information.
767 my ($biblionumber, $status, $msg, $location) = _availability($id);
772 my ($itemnumber) = @_;
773 my $item = GetItem( $itemnumber, undef, undef );
775 if ( not $item->{'itemnumber'} ) {
776 return ( undef, 'unknown', 'Error: could not retrieve availability for this ID', undef );
779 my $biblionumber = $item->{'biblioitemnumber'};
780 my $library = Koha::Libraries->find( $item->{holdingbranch} );
781 my $location = $library ? $library->branchname : '';
783 if ( $item->{'notforloan'} ) {
784 return ( $biblionumber, 'not available', 'Not for loan', $location );
785 } elsif ( $item->{'onloan'} ) {
786 return ( $biblionumber, 'not available', 'Checked out', $location );
787 } elsif ( $item->{'itemlost'} ) {
788 return ( $biblionumber, 'not available', 'Item lost', $location );
789 } elsif ( $item->{'withdrawn'} ) {
790 return ( $biblionumber, 'not available', 'Item withdrawn', $location );
791 } elsif ( $item->{'damaged'} ) {
792 return ( $biblionumber, 'not available', 'Item damaged', $location );
794 return ( $biblionumber, 'available', undef, $location );