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 # Get most of the needed data
209 my $biblioitemnumber = $biblioitem->{'biblioitemnumber'};
210 my $reserves = GetReservesFromBiblionumber({ biblionumber => $biblionumber });
211 my $issues = GetBiblioIssues($biblionumber);
212 my $items = GetItemsByBiblioitemnumber($biblioitemnumber);
214 # We loop over the items to clean them
215 foreach my $item (@$items) {
217 # This hides additionnal XML subfields, we don't need these info
218 delete $item->{'more_subfields_xml'};
220 # Display branch names instead of branch codes
221 my $home_library = Koha::Libraries->find( $item->{homebranch} );
222 my $holding_library = Koha::Libraries->find( $item->{holdingbranch} );
223 $item->{'homebranchname'} = $home_library ? $home_library->branchname : '';
224 $item->{'holdingbranchname'} = $holding_library ? $holding_library->branchname : '';
227 # Hashref building...
228 $biblioitem->{'items'}->{'item'} = $items;
229 $biblioitem->{'reserves'}->{'reserve'} = $reserves;
230 $biblioitem->{'issues'}->{'issue'} = $issues;
232 push @records, $biblioitem;
235 return { record => \@records };
238 =head2 GetAuthorityRecords
240 Given a list of authority record identifiers, returns a list of record
241 objects that contain the authority records. The function user may request
242 a specific metadata schema for the record objects.
247 list of authority record identifiers
249 specifies the metadata schema of records to be returned, possible values:
254 sub GetAuthorityRecords {
257 # If the user asks for an unsupported schema, return an error code
258 if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
259 return { code => 'UnsupportedSchema' };
264 # Let's loop over the authority IDs
265 foreach my $authid ( split( / /, $cgi->param('id') ) ) {
267 # Get the record as XML string, or error code
268 push @records, GetAuthorityXML($authid) || { code => 'RecordNotFound' };
271 return { record => \@records };
276 Looks up a patron in the ILS by an identifier, and returns the borrowernumber.
281 an identifier used to look up the patron in Koha
283 the type of the identifier, possible values:
294 # Get the borrower...
295 my $borrower = GetMember($cgi->param('id_type') => $cgi->param('id'));
296 if ( not $borrower->{'borrowernumber'} ) {
297 return { message => 'PatronNotFound' };
301 my $patron->{'id'} = $borrower->{'borrowernumber'};
302 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
304 # ...and return his ID
308 =head2 AuthenticatePatron
310 Authenticates a user's login credentials and returns the identifier for
315 - username (Required)
316 user's login identifier (userid or cardnumber)
317 - password (Required)
322 sub AuthenticatePatron {
324 my $username = $cgi->param('username');
325 my $password = $cgi->param('password');
326 my ($status, $cardnumber, $userid) = C4::Auth::checkpw( C4::Context->dbh, $username, $password );
329 my $borrower = GetMember( cardnumber => $cardnumber );
330 my $patron->{'id'} = $borrower->{'borrowernumber'};
334 return { code => 'PatronNotFound' };
340 Returns specified information about the patron, based on options in the
341 request. This function can optionally return patron's contact information,
342 fine information, hold request information, and loan information.
346 - patron_id (Required)
348 - show_contact (Optional, default 1)
349 whether or not to return patron's contact information in the response
350 - show_fines (Optional, default 0)
351 whether or not to return fine information in the response
352 - show_holds (Optional, default 0)
353 whether or not to return hold request information in the response
354 - show_loans (Optional, default 0)
355 whether or not to return loan information request information in the response
363 my $borrowernumber = $cgi->param('patron_id');
364 my $borrower = GetMember( borrowernumber => $borrowernumber );
365 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
367 # Cleaning the borrower hashref
368 my $flags = C4::Members::patronflags( $borrower );
369 $borrower->{'charges'} = $flags>{'CHARGES'}->{'amount'};
370 my $library = Koha::Libraries->find( $borrower->{branchcode} );
371 $borrower->{'branchname'} = $library ? $library->branchname : '';
372 delete $borrower->{'userid'};
373 delete $borrower->{'password'};
375 # Contact fields management
376 if ( defined $cgi->param('show_contact') && $cgi->param('show_contact') eq "0" ) {
378 # Define contact fields
379 my @contactfields = (
380 'email', 'emailpro', 'fax', 'mobile', 'phone', 'phonepro',
381 'streetnumber', 'zipcode', 'city', 'streettype', 'B_address', 'B_city',
382 'B_email', 'B_phone', 'B_zipcode', 'address', 'address2', 'altcontactaddress1',
383 'altcontactaddress2', 'altcontactaddress3', 'altcontactfirstname', 'altcontactphone', 'altcontactsurname', 'altcontactzipcode'
387 foreach my $field (@contactfields) {
388 delete $borrower->{$field};
393 if ( $cgi->param('show_fines') && $cgi->param('show_fines') eq "1" ) {
395 for ( my $i = 1 ; my @charge = getcharges( $borrowernumber, undef, $i ) ; $i++ ) {
396 push( @charges, @charge );
398 $borrower->{'fines'}->{'fine'} = \@charges;
401 # Reserves management
402 if ( $cgi->param('show_holds') && $cgi->param('show_holds') eq "1" ) {
404 # Get borrower's reserves
405 my @reserves = GetReservesFromBorrowernumber( $borrowernumber, undef );
406 foreach my $reserve (@reserves) {
408 # Get additional informations
409 my $item = GetBiblioFromItemNumber( $reserve->{'itemnumber'}, undef );
410 my $library = Koha::Libraries->find( $reserve->{branchcode} );
411 my $branchname = $library ? $library->branchname : '';
413 # Remove unwanted fields
414 delete $item->{'marcxml'};
415 delete $item->{'more_subfields_xml'};
417 # Add additional fields
418 $reserve->{'item'} = $item;
419 $reserve->{'branchname'} = $branchname;
420 $reserve->{'title'} = GetBiblio( $reserve->{'biblionumber'} )->{'title'};
422 $borrower->{'holds'}->{'hold'} = \@reserves;
426 if ( $cgi->param('show_loans') && $cgi->param('show_loans') eq "1" ) {
427 my $issues = GetPendingIssues($borrowernumber);
428 foreach my $issue ( @$issues ){
429 $issue->{'issuedate'} = $issue->{'issuedate'}->strftime('%Y-%m-%d %H:%M');
430 $issue->{'date_due'} = $issue->{'date_due'}->strftime('%Y-%m-%d %H:%M');
432 $borrower->{'loans'}->{'loan'} = $issues;
435 if ( $cgi->param('show_attributes') eq "1" ) {
436 my $attrs = GetBorrowerAttributes( $borrowernumber, 0, 1 );
437 $borrower->{'attributes'} = $attrs;
443 =head2 GetPatronStatus
445 Returns a patron's status information.
449 - patron_id (Required)
454 sub GetPatronStatus {
458 my $borrowernumber = $cgi->param('patron_id');
459 my $borrower = GetMember( borrowernumber => $borrowernumber );
460 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
464 type => $$borrower{categorycode},
466 expiry => $$borrower{dateexpiry},
472 Returns information about the services available on a particular item for
477 - patron_id (Required)
486 # Get the member, or return an error code if not found
487 my $borrowernumber = $cgi->param('patron_id');
488 my $borrower = GetMember( borrowernumber => $borrowernumber );
489 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
491 # Get the item, or return an error code if not found
492 my $itemnumber = $cgi->param('item_id');
493 my $item = GetItem( $itemnumber );
494 return { code => 'RecordNotFound' } unless $$item{itemnumber};
498 # Reserve level management
499 my $biblionumber = $item->{'biblionumber'};
500 my $canbookbereserved = CanBookBeReserved( $borrower, $biblionumber );
501 if ($canbookbereserved eq 'OK') {
502 push @availablefor, 'title level hold';
503 my $canitembereserved = IsAvailableForItemLevelRequest($item, $borrower);
504 if ($canitembereserved) {
505 push @availablefor, 'item level hold';
509 # Reserve cancellation management
510 my @reserves = GetReservesFromBorrowernumber( $borrowernumber, undef );
512 foreach my $reserve (@reserves) {
513 push @reserveditems, $reserve->{'itemnumber'};
515 if ( grep { $itemnumber eq $_ } @reserveditems ) {
516 push @availablefor, 'hold cancellation';
520 my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
522 push @availablefor, 'loan renewal';
526 my $barcode = $item->{'barcode'} || '';
527 $barcode = barcodedecode($barcode) if ( $barcode && C4::Context->preference('itemBarcodeInputFilter') );
529 my ( $issuingimpossible, $needsconfirmation ) = CanBookBeIssued( $borrower, $barcode );
531 # TODO push @availablefor, 'loan';
535 $out->{'AvailableFor'} = \@availablefor;
542 Extends the due date for a borrower's existing issue.
546 - patron_id (Required)
550 - desired_due_date (Required)
551 the date the patron would like the item returned by
558 # Get borrower infos or return an error code
559 my $borrowernumber = $cgi->param('patron_id');
560 my $borrower = GetMember( borrowernumber => $borrowernumber );
561 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
563 # Get the item, or return an error code
564 my $itemnumber = $cgi->param('item_id');
565 my $item = GetItem( $itemnumber );
566 return { code => 'RecordNotFound' } unless $$item{itemnumber};
568 # Add renewal if possible
569 my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
570 if ( $renewal[0] ) { AddRenewal( $borrowernumber, $itemnumber ); }
572 my $issue = GetItemIssue($itemnumber);
576 $out->{'renewals'} = $issue->{'renewals'};
577 $out->{date_due} = $issue->{date_due}->strftime('%Y-%m-%d %H:%S');
578 $out->{'success'} = $renewal[0];
579 $out->{'error'} = $renewal[1];
586 Creates, for a borrower, a biblio-level hold reserve.
590 - patron_id (Required)
594 - request_location (Required)
595 IP address where the end user request is being placed
596 - pickup_location (Optional)
597 a branch code indicating the location to which to deliver the item for pickup
598 - needed_before_date (Optional)
599 date after which hold request is no longer needed
600 - pickup_expiry_date (Optional)
601 date after which item returned to shelf if item is not picked up
608 # Get the borrower or return an error code
609 my $borrowernumber = $cgi->param('patron_id');
610 my $borrower = GetMember( borrowernumber => $borrowernumber );
611 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
613 # Get the biblio record, or return an error code
614 my $biblionumber = $cgi->param('bib_id');
615 my $biblio = GetBiblio( $biblionumber );
616 return { code => 'RecordNotFound' } unless $$biblio{biblionumber};
618 my $title = $$biblio{title};
620 # Check if the biblio can be reserved
621 return { code => 'NotHoldable' } unless CanBookBeReserved( $borrowernumber, $biblionumber ) eq 'OK';
625 # Pickup branch management
626 if ( $cgi->param('pickup_location') ) {
627 $branch = $cgi->param('pickup_location');
628 return { code => 'LocationNotFound' } unless Koha::Libraries->find($branch);
629 } else { # if the request provide no branch, use the borrower's branch
630 $branch = $$borrower{branchcode};
634 # $branch, $borrowernumber, $biblionumber,
635 # $constraint, $bibitems, $priority, $resdate, $expdate, $notes,
636 # $title, $checkitem, $found
637 my $priority= C4::Reserves::CalculatePriority( $biblionumber );
638 AddReserve( $branch, $borrowernumber, $biblionumber, undef, $priority, undef, undef, undef, $title, undef, undef );
642 $out->{'title'} = $title;
643 my $library = Koha::Libraries->find( $branch );
644 $out->{'pickup_location'} = $library ? $library->branchname : '';
646 # TODO $out->{'date_available'} = '';
653 Creates, for a borrower, an item-level hold request on a specific item of
654 a bibliographic record in Koha.
658 - patron_id (Required)
664 - pickup_location (Optional)
665 a branch code indicating the location to which to deliver the item for pickup
666 - needed_before_date (Optional)
667 date after which hold request is no longer needed
668 - pickup_expiry_date (Optional)
669 date after which item returned to shelf if item is not picked up
676 # Get the borrower or return an error code
677 my $borrowernumber = $cgi->param('patron_id');
678 my $borrower = GetMember( borrowernumber => $borrowernumber );
679 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
681 # Get the biblio or return an error code
682 my $biblionumber = $cgi->param('bib_id');
683 my $biblio = GetBiblio($biblionumber);
684 return { code => 'RecordNotFound' } unless $$biblio{biblionumber};
686 my $title = $$biblio{title};
688 # Get the item or return an error code
689 my $itemnumber = $cgi->param('item_id');
690 my $item = GetItem( $itemnumber );
691 return { code => 'RecordNotFound' } unless $$item{itemnumber};
693 # If the biblio does not match the item, return an error code
694 return { code => 'RecordNotFound' } if $$item{biblionumber} ne $$biblio{biblionumber};
696 # Check for item disponibility
697 my $canitembereserved = C4::Reserves::CanItemBeReserved( $borrowernumber, $itemnumber );
698 my $canbookbereserved = C4::Reserves::CanBookBeReserved( $borrowernumber, $biblionumber );
699 return { code => 'NotHoldable' } unless $canbookbereserved eq 'OK' and $canitembereserved eq 'OK';
701 # Pickup branch management
703 if ( $cgi->param('pickup_location') ) {
704 $branch = $cgi->param('pickup_location');
705 return { code => 'LocationNotFound' } unless Koha::Libraries->find($branch);
706 } else { # if the request provide no branch, use the borrower's branch
707 $branch = $$borrower{branchcode};
711 # $branch, $borrowernumber, $biblionumber,
712 # $constraint, $bibitems, $priority, $resdate, $expdate, $notes,
713 # $title, $checkitem, $found
714 my $priority= C4::Reserves::CalculatePriority( $biblionumber );
715 AddReserve( $branch, $borrowernumber, $biblionumber, undef, $priority, undef, undef, undef, $title, $itemnumber, undef );
719 my $library = Koha::Libraries->find( $branch );
720 $out->{'pickup_location'} = $library ? $library->branchname : '';
722 # TODO $out->{'date_available'} = '';
729 Cancels an active reserve request for the borrower.
733 - patron_id (Required)
743 # Get the borrower or return an error code
744 my $borrowernumber = $cgi->param('patron_id');
745 my $borrower = GetMember( borrowernumber => $borrowernumber );
746 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
748 # Get the reserve or return an error code
749 my $reserve_id = $cgi->param('item_id');
750 my $reserve = C4::Reserves::GetReserve($reserve_id);
751 return { code => 'RecordNotFound' } unless $reserve;
752 return { code => 'RecordNotFound' } unless ($reserve->{borrowernumber} == $borrowernumber);
754 C4::Reserves::CancelReserve({reserve_id => $reserve_id});
756 return { code => 'Canceled' };
761 Returns, for an itemnumber, an array containing availability information.
763 my ($biblionumber, $status, $msg, $location) = _availability($id);
768 my ($itemnumber) = @_;
769 my $item = GetItem( $itemnumber, undef, undef );
771 if ( not $item->{'itemnumber'} ) {
772 return ( undef, 'unknown', 'Error: could not retrieve availability for this ID', undef );
775 my $biblionumber = $item->{'biblioitemnumber'};
776 my $library = Koha::Libraries->find( $item->{holdingbranch} );
777 my $location = $library ? $library->branchname : '';
779 if ( $item->{'notforloan'} ) {
780 return ( $biblionumber, 'not available', 'Not for loan', $location );
781 } elsif ( $item->{'onloan'} ) {
782 return ( $biblionumber, 'not available', 'Checked out', $location );
783 } elsif ( $item->{'itemlost'} ) {
784 return ( $biblionumber, 'not available', 'Item lost', $location );
785 } elsif ( $item->{'withdrawn'} ) {
786 return ( $biblionumber, 'not available', 'Item withdrawn', $location );
787 } elsif ( $item->{'damaged'} ) {
788 return ( $biblionumber, 'not available', 'Item damaged', $location );
790 return ( $biblionumber, 'available', undef, $location );