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);
31 use C4::AuthoritiesMarc;
32 use C4::ILSDI::Utility;
39 C4::ILS-DI::Services - ILS-DI Services
43 Each function in this module represents an ILS-DI service.
44 They all takes a CGI instance as argument and most of them return a
45 hashref that will be printed by XML::Simple in opac/ilsdi.pl
49 use C4::ILSDI::Services;
55 $out = LookupPatron($cgi);
57 print CGI::header('text/xml');
62 xmldecl => '<?xml version="1.0" encoding="ISO-8859-1" ?>',
63 RootName => 'LookupPatron',
70 =head2 GetAvailability
72 Given a set of biblionumbers or itemnumbers, returns a list with
73 availability of the items associated with the identifiers.
79 list of either biblionumbers or itemnumbers
81 =head3 id_type (Required)
83 defines the type of record identifier being used in the request,
89 =head3 return_type (Optional)
91 requests a particular level of detail in reporting availability,
97 =head3 return_fmt (Optional)
99 requests a particular format or set of formats in reporting
104 sub GetAvailability {
107 my $out = "<?xml version=\"1.0\" encoding=\"ISO-8859-1\" ?>\n";
108 $out .= "<dlf:collection\n";
109 $out .= " xmlns:dlf=\"http://diglib.org/ilsdi/1.1\"\n";
110 $out .= " xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n";
111 $out .= " xsi:schemaLocation=\"http://diglib.org/ilsdi/1.1\n";
112 $out .= " http://diglib.org/architectures/ilsdi/schemas/1.1/dlfexpanded.xsd\">\n";
114 foreach my $id ( split( / /, $cgi->param('id') ) ) {
115 if ( $cgi->param('id_type') eq "item" ) {
116 my ( $biblionumber, $status, $msg, $location ) = Availability($id);
118 $out .= " <dlf:record>\n";
119 $out .= " <dlf:bibliographic id=\"" . ( $biblionumber || $id ) . "\" />\n";
120 $out .= " <dlf:items>\n";
121 $out .= " <dlf:item id=\"" . $id . "\">\n";
122 $out .= " <dlf:simpleavailability>\n";
123 $out .= " <dlf:identifier>" . $id . "</dlf:identifier>\n";
124 $out .= " <dlf:availabilitystatus>" . $status . "</dlf:availabilitystatus>\n";
125 if ($msg) { $out .= " <dlf:availabilitymsg>" . $msg . "</dlf:availabilitymsg>\n"; }
126 if ($location) { $out .= " <dlf:location>" . $location . "</dlf:location>\n"; }
127 $out .= " </dlf:simpleavailability>\n";
128 $out .= " </dlf:item>\n";
129 $out .= " </dlf:items>\n";
130 $out .= " </dlf:record>\n";
134 my $biblioitem = ( GetBiblioItemByBiblioNumber( $id, undef ) )[0];
139 $msg = "Error: could not retrieve availability for this ID";
141 $out .= " <dlf:record>\n";
142 $out .= " <dlf:bibliographic id=\"" . $id . "\" />\n";
143 $out .= " <dlf:simpleavailability>\n";
144 $out .= " <dlf:identifier>" . $id . "</dlf:identifier>\n";
145 $out .= " <dlf:availabilitystatus>" . $status . "</dlf:availabilitystatus>\n";
146 $out .= " <dlf:availabilitymsg>" . $msg . "</dlf:availabilitymsg>\n";
147 $out .= " </dlf:simpleavailability>\n";
148 $out .= " </dlf:record>\n";
151 $out .= "</dlf:collection>\n";
158 Given a list of biblionumbers, returns a list of record objects that
159 contain bibliographic information, as well as associated holdings and item
160 information. The caller may request a specific metadata schema for the
161 record objects to be returned.
163 This function behaves similarly to HarvestBibliographicRecords and
164 HarvestExpandedRecords in Data Aggregation, but allows quick, real time
165 lookup by bibliographic identifier.
167 You can use OAI-PMH ListRecords instead of this service.
172 list of system record identifiers
174 Defines the metadata schema in which the records are returned,
183 # Check if the schema is supported. For now, GetRecords only supports MARCXML
184 if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
185 return { code => 'UnsupportedSchema' };
190 # Loop over biblionumbers
191 foreach my $biblionumber ( split( / /, $cgi->param('id') ) ) {
193 # Get the biblioitem from the biblionumber
194 my $biblioitem = ( GetBiblioItemByBiblioNumber( $biblionumber, undef ) )[0];
195 if ( not $biblioitem->{'biblionumber'} ) {
196 $biblioitem->{code} = "RecordNotFound";
199 # We don't want MARC to be displayed
200 delete $biblioitem->{'marc'};
202 # Get most of the needed data
203 my $biblioitemnumber = $biblioitem->{'biblioitemnumber'};
204 my @reserves = GetReservesFromBiblionumber( $biblionumber, undef, undef );
205 my $issues = GetBiblioIssues($biblionumber);
206 my $items = GetItemsByBiblioitemnumber($biblioitemnumber);
208 # We loop over the items to clean them
209 foreach my $item (@$items) {
211 # This hides additionnal XML subfields, we don't need these info
212 delete $item->{'more_subfields_xml'};
214 # Display branch names instead of branch codes
215 $item->{'homebranchname'} = GetBranchName( $item->{'homebranch'} );
216 $item->{'holdingbranchname'} = GetBranchName( $item->{'holdingbranch'} );
219 # Hashref building...
220 $biblioitem->{'items'}->{'item'} = $items;
221 $biblioitem->{'reserves'}->{'reserve'} = $reserves[1];
222 $biblioitem->{'issues'}->{'issue'} = $issues;
224 push @records, $biblioitem;
227 return { record => \@records };
230 =head2 GetAuthorityRecords
232 Given a list of authority record identifiers, returns a list of record
233 objects that contain the authority records. The function user may request
234 a specific metadata schema for the record objects.
239 list of authority record identifiers
241 specifies the metadata schema of records to be returned, possible values:
246 sub GetAuthorityRecords {
249 # If the user asks for an unsupported schema, return an error code
250 if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
251 return { code => 'UnsupportedSchema' };
256 # Let's loop over the authority IDs
257 foreach my $authid ( split( / /, $cgi->param('id') ) ) {
259 # Get the record as XML string, or error code
260 push @records, GetAuthorityXML($authid) || { code => 'RecordNotFound' };
263 return { record => \@records };
268 Looks up a patron in the ILS by an identifier, and returns the borrowernumber.
273 an identifier used to look up the patron in Koha
275 the type of the identifier, possible values:
286 # Get the borrower...
287 my $borrower = GetMember($cgi->param('id_type') => $cgi->param('id'));
288 if ( not $borrower->{'borrowernumber'} ) {
289 return { message => 'PatronNotFound' };
293 my $patron->{'id'} = $borrower->{'borrowernumber'};
294 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
296 # ...and return his ID
300 =head2 AuthenticatePatron
302 Authenticates a user's login credentials and returns the identifier for
307 - username (Required)
308 user's login identifier
309 - password (Required)
314 sub AuthenticatePatron {
317 # Check if borrower exists, using a C4::Auth function...
318 unless( checkpw( C4::Context->dbh, $cgi->param('username'), $cgi->param('password') ) ) {
319 return { code => 'PatronNotFound' };
323 my $borrower = GetMember( userid => $cgi->param('username') );
326 my $patron->{'id'} = $borrower->{'borrowernumber'};
328 # ... and return his ID
334 Returns specified information about the patron, based on options in the
335 request. This function can optionally return patron's contact information,
336 fine information, hold request information, and loan information.
340 - patron_id (Required)
342 - show_contact (Optional, default 1)
343 whether or not to return patron's contact information in the response
344 - show_fines (Optional, default 0)
345 whether or not to return fine information in the response
346 - show_holds (Optional, default 0)
347 whether or not to return hold request information in the response
348 - show_loans (Optional, default 0)
349 whether or not to return loan information request information in the response
357 my $borrowernumber = $cgi->param('patron_id');
358 my $borrower = GetMemberDetails( $borrowernumber );
359 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
361 # Cleaning the borrower hashref
362 $borrower->{'charges'} = $borrower->{'flags'}->{'CHARGES'}->{'amount'};
363 $borrower->{'branchname'} = GetBranchName( $borrower->{'branchcode'} );
364 delete $borrower->{'flags'};
365 delete $borrower->{'userid'};
366 delete $borrower->{'password'};
368 # Contact fields management
369 if ( $cgi->param('show_contact') eq "0" ) {
371 # Define contact fields
372 my @contactfields = (
373 'email', 'emailpro', 'fax', 'mobile', 'phone', 'phonepro',
374 'streetnumber', 'zipcode', 'city', 'streettype', 'B_address', 'B_city',
375 'B_email', 'B_phone', 'B_zipcode', 'address', 'address2', 'altcontactaddress1',
376 'altcontactaddress2', 'altcontactaddress3', 'altcontactfirstname', 'altcontactphone', 'altcontactsurname', 'altcontactzipcode'
380 foreach my $field (@contactfields) {
381 delete $borrower->{$field};
386 if ( $cgi->param('show_fines') eq "1" ) {
388 for ( my $i = 1 ; my @charge = getcharges( $borrowernumber, undef, $i ) ; $i++ ) {
389 push( @charges, @charge );
391 $borrower->{'fines'}->{'fine'} = \@charges;
394 # Reserves management
395 if ( $cgi->param('show_holds') eq "1" ) {
397 # Get borrower's reserves
398 my @reserves = GetReservesFromBorrowernumber( $borrowernumber, undef );
399 foreach my $reserve (@reserves) {
401 # Get additional informations
402 my $item = GetBiblioFromItemNumber( $reserve->{'itemnumber'}, undef );
403 my $branchname = GetBranchName( $reserve->{'branchcode'} );
405 # Remove unwanted fields
406 delete $item->{'marc'};
407 delete $item->{'marcxml'};
408 delete $item->{'more_subfields_xml'};
410 # Add additional fields
411 $reserve->{'item'} = $item;
412 $reserve->{'branchname'} = $branchname;
413 $reserve->{'title'} = ( GetBiblio( $reserve->{'biblionumber'} ) )[1]->{'title'};
415 $borrower->{'holds'}->{'hold'} = \@reserves;
419 if ( $cgi->param('show_loans') eq "1" ) {
420 my $issues = GetPendingIssues($borrowernumber);
421 $borrower->{'loans'}->{'loan'} = $issues;
427 =head2 GetPatronStatus
429 Returns a patron's status information.
433 - patron_id (Required)
438 sub GetPatronStatus {
442 my $borrowernumber = $cgi->param('patron_id');
443 my $borrower = GetMemberDetails( $borrowernumber );
444 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
448 type => $$borrower{categorycode},
450 expiry => $$borrower{dateexpiry},
456 Returns information about the services available on a particular item for
461 - patron_id (Required)
470 # Get the member, or return an error code if not found
471 my $borrowernumber = $cgi->param('patron_id');
472 my $borrower = GetMemberDetails( $borrowernumber );
473 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
475 # Get the item, or return an error code if not found
476 my $itemnumber = $cgi->param('item_id');
477 my $item = GetItem( $itemnumber );
478 return { code => 'RecordNotFound' } unless $$item{itemnumber};
482 # Reserve level management
483 my $biblionumber = $item->{'biblionumber'};
484 my $canbookbereserved = CanBookBeReserved( $borrower, $biblionumber );
485 if ($canbookbereserved) {
486 push @availablefor, 'title level hold';
487 my $canitembereserved = IsAvailableForItemLevelRequest($itemnumber);
488 if ($canitembereserved) {
489 push @availablefor, 'item level hold';
493 # Reserve cancellation management
494 my @reserves = GetReservesFromBorrowernumber( $borrowernumber, undef );
496 foreach my $reserve (@reserves) {
497 push @reserveditems, $reserve->{'itemnumber'};
499 if ( grep { $itemnumber eq $_ } @reserveditems ) {
500 push @availablefor, 'hold cancellation';
504 my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
506 push @availablefor, 'loan renewal';
510 my $barcode = $item->{'barcode'} || '';
511 $barcode = barcodedecode($barcode) if ( $barcode && C4::Context->preference('itemBarcodeInputFilter') );
513 my ( $issuingimpossible, $needsconfirmation ) = CanBookBeIssued( $borrower, $barcode );
515 # TODO push @availablefor, 'loan';
519 $out->{'AvailableFor'} = \@availablefor;
526 Extends the due date for a borrower's existing issue.
530 - patron_id (Required)
534 - desired_due_date (Required)
535 the date the patron would like the item returned by
542 # Get borrower infos or return an error code
543 my $borrowernumber = $cgi->param('patron_id');
544 my $borrower = GetMemberDetails( $borrowernumber );
545 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
547 # Get the item, or return an error code
548 my $itemnumber = $cgi->param('item_id');
549 my $item = GetItem( $itemnumber );
550 return { code => 'RecordNotFound' } unless $$item{itemnumber};
552 # Add renewal if possible
553 my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
554 if ( $renewal[0] ) { AddRenewal( $borrowernumber, $itemnumber ); }
556 my $issue = GetItemIssue($itemnumber);
560 $out->{'renewals'} = $issue->{'renewals'};
561 $out->{'date_due'} = $issue->{'date_due'};
562 $out->{'success'} = $renewal[0];
563 $out->{'error'} = $renewal[1];
570 Creates, for a borrower, a biblio-level hold reserve.
574 - patron_id (Required)
578 - request_location (Required)
579 IP address where the end user request is being placed
580 - pickup_location (Optional)
581 a branch code indicating the location to which to deliver the item for pickup
582 - needed_before_date (Optional)
583 date after which hold request is no longer needed
584 - pickup_expiry_date (Optional)
585 date after which item returned to shelf if item is not picked up
592 # Get the borrower or return an error code
593 my $borrowernumber = $cgi->param('patron_id');
594 my $borrower = GetMemberDetails( $borrowernumber );
595 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
597 # Get the biblio record, or return an error code
598 my $biblionumber = $cgi->param('bib_id');
599 my ( $count, $biblio ) = GetBiblio( $biblionumber );
600 return { code => 'RecordNotFound' } unless $$biblio{biblionumber};
602 my $title = $$biblio{title};
604 # Check if the biblio can be reserved
605 return { code => 'NotHoldable' } unless CanBookBeReserved( $borrowernumber, $biblionumber );
609 # Pickup branch management
610 if ( $cgi->param('pickup_location') ) {
611 $branch = $cgi->param('pickup_location');
612 my $branches = GetBranches;
613 return { code => 'LocationNotFound' } unless $$branches{$branch};
614 } else { # if the request provide no branch, use the borrower's branch
615 $branch = $$borrower{branchcode};
619 # $branch, $borrowernumber, $biblionumber, $constraint, $bibitems, $priority, $notes, $title, $checkitem, $found
620 AddReserve( $branch, $borrowernumber, $biblionumber, 'a', undef, 0, undef, $title, undef, undef );
624 $out->{'title'} = $title;
625 $out->{'pickup_location'} = GetBranchName($branch);
627 # TODO $out->{'date_available'} = '';
634 Creates, for a borrower, an item-level hold request on a specific item of
635 a bibliographic record in Koha.
639 - patron_id (Required)
645 - pickup_location (Optional)
646 a branch code indicating the location to which to deliver the item for pickup
647 - needed_before_date (Optional)
648 date after which hold request is no longer needed
649 - pickup_expiry_date (Optional)
650 date after which item returned to shelf if item is not picked up
657 # Get the borrower or return an error code
658 my $borrowernumber = $cgi->param('patron_id');
659 my $borrower = GetMemberDetails( $borrowernumber );
660 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
662 # Get the biblio or return an error code
663 my $biblionumber = $cgi->param('bib_id');
664 my ( $count, $biblio ) = GetBiblio($biblionumber);
665 return { code => 'RecordNotFound' } unless $$biblio{biblionumber};
667 my $title = $$biblio{title};
669 # Get the item or return an error code
670 my $itemnumber = $cgi->param('item_id');
671 my $item = GetItem( $itemnumber );
672 return { code => 'RecordNotFound' } unless $$item{itemnumber};
674 # If the biblio does not match the item, return an error code
675 return { code => 'RecordNotFound' } if $$item{biblionumber} ne $$biblio{biblionumber};
677 # Check for item disponibility
678 my $canitembereserved = CanItemBeReserved( $borrowernumber, $itemnumber );
679 my $canbookbereserved = CanBookBeReserved( $borrowernumber, $biblionumber );
680 return { code => 'NotHoldable' } unless $canbookbereserved and $canitembereserved;
684 # Pickup branch management
685 if ( $cgi->param('pickup_location') ) {
686 $branch = $cgi->param('pickup_location');
687 my $branches = GetBranches();
688 return { code => 'LocationNotFound' } unless $$branches{$branch};
689 } else { # if the request provide no branch, use the borrower's branch
690 $branch = $$borrower{branchcode};
697 $rank = '0' unless C4::Context->preference('ReservesNeedReturns');
698 if ( $item->{'holdingbranch'} eq $branch ) {
699 $found = 'W' unless C4::Context->preference('ReservesNeedReturns');
703 # $branch, $borrowernumber, $biblionumber, $constraint, $bibitems, $priority, $notes, $title, $checkitem, $found
704 AddReserve( $branch, $borrowernumber, $biblionumber, 'a', undef, $rank, undef, $title, $itemnumber, $found );
708 $out->{'pickup_location'} = GetBranchName($branch);
710 # TODO $out->{'date_available'} = '';
717 Cancels an active reserve request for the borrower.
721 - patron_id (Required)
731 # Get the borrower or return an error code
732 my $borrowernumber = $cgi->param('patron_id');
733 my $borrower = GetMemberDetails( $borrowernumber );
734 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
736 # Get the item or return an error code
737 my $itemnumber = $cgi->param('item_id');
738 my $item = GetItem( $itemnumber );
739 return { code => 'RecordNotFound' } unless $$item{itemnumber};
741 # Get borrower's reserves
742 my @reserves = GetReservesFromBorrowernumber( $borrowernumber, undef );
745 # ...and loop over it to build an array of reserved itemnumbers
746 foreach my $reserve (@reserves) {
747 push @reserveditems, $reserve->{'itemnumber'};
750 # if the item was not reserved by the borrower, returns an error code
751 return { code => 'NotCanceled' } unless any { $itemnumber eq $_ } @reserveditems;
754 CancelReserve( $itemnumber, undef, $borrowernumber );
756 return { code => 'Canceled' };