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.
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',
68 =head2 GetAvailability
70 Given a set of biblionumbers or itemnumbers, returns a list with
71 availability of the items associated with the identifiers.
76 list of either biblionumbers or itemnumbers
78 defines the type of record identifier being used in the request,
82 - return_type (Optional)
83 requests a particular level of detail in reporting availability,
87 - return_fmt (Optional)
88 requests a particular format or set of formats in reporting
96 my $out = "<?xml version=\"1.0\" encoding=\"ISO-8859-1\" ?>\n";
97 $out .= "<dlf:collection\n";
98 $out .= " xmlns:dlf=\"http://diglib.org/ilsdi/1.1\"\n";
99 $out .= " xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n";
100 $out .= " xsi:schemaLocation=\"http://diglib.org/ilsdi/1.1\n";
101 $out .= " http://diglib.org/architectures/ilsdi/schemas/1.1/dlfexpanded.xsd\">\n";
103 foreach my $id ( split( / /, $cgi->param('id') ) ) {
104 if ( $cgi->param('id_type') eq "item" ) {
105 my ( $biblionumber, $status, $msg, $location ) = Availability($id);
107 $out .= " <dlf:record>\n";
108 $out .= " <dlf:bibliographic id=\"" . ( $biblionumber || $id ) . "\" />\n";
109 $out .= " <dlf:items>\n";
110 $out .= " <dlf:item id=\"" . $id . "\">\n";
111 $out .= " <dlf:simpleavailability>\n";
112 $out .= " <dlf:identifier>" . $id . "</dlf:identifier>\n";
113 $out .= " <dlf:availabilitystatus>" . $status . "</dlf:availabilitystatus>\n";
114 if ($msg) { $out .= " <dlf:availabilitymsg>" . $msg . "</dlf:availabilitymsg>\n"; }
115 if ($location) { $out .= " <dlf:location>" . $location . "</dlf:location>\n"; }
116 $out .= " </dlf:simpleavailability>\n";
117 $out .= " </dlf:item>\n";
118 $out .= " </dlf:items>\n";
119 $out .= " </dlf:record>\n";
123 my $biblioitem = ( GetBiblioItemByBiblioNumber( $id, undef ) )[0];
128 $msg = "Error: could not retrieve availability for this ID";
130 $out .= " <dlf:record>\n";
131 $out .= " <dlf:bibliographic id=\"" . $id . "\" />\n";
132 $out .= " <dlf:simpleavailability>\n";
133 $out .= " <dlf:identifier>" . $id . "</dlf:identifier>\n";
134 $out .= " <dlf:availabilitystatus>" . $status . "</dlf:availabilitystatus>\n";
135 $out .= " <dlf:availabilitymsg>" . $msg . "</dlf:availabilitymsg>\n";
136 $out .= " </dlf:simpleavailability>\n";
137 $out .= " </dlf:record>\n";
140 $out .= "</dlf:collection>\n";
147 Given a list of biblionumbers, returns a list of record objects that
148 contain bibliographic information, as well as associated holdings and item
149 information. The caller may request a specific metadata schema for the
150 record objects to be returned.
151 This function behaves similarly to HarvestBibliographicRecords and
152 HarvestExpandedRecords in Data Aggregation, but allows quick, real time
153 lookup by bibliographic identifier.
155 You can use OAI-PMH ListRecords instead of this service.
160 list of system record identifiers
162 Defines the metadata schema in which the records are returned,
171 # Check if the schema is supported. For now, GetRecords only supports MARCXML
172 if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
173 return { code => 'UnsupportedSchema' };
178 # Loop over biblionumbers
179 foreach my $biblionumber ( split( / /, $cgi->param('id') ) ) {
181 # Get the biblioitem from the biblionumber
182 my $biblioitem = ( GetBiblioItemByBiblioNumber( $biblionumber, undef ) )[0];
183 if ( not $biblioitem->{'biblionumber'} ) {
184 $biblioitem = "RecordNotFound";
187 # We don't want MARC to be displayed
188 delete $biblioitem->{'marc'};
190 # nor the XML declaration of MARCXML
191 $biblioitem->{'marcxml'} =~ s/<\?xml version="1.0" encoding="UTF-8"\?>//go;
193 # Get most of the needed data
194 my $biblioitemnumber = $biblioitem->{'biblioitemnumber'};
195 my @reserves = GetReservesFromBiblionumber( $biblionumber, undef, undef );
196 my $issues = GetBiblioIssues($biblionumber);
197 my $items = GetItemsByBiblioitemnumber($biblioitemnumber);
199 # We loop over the items to clean them
200 foreach my $item (@$items) {
202 # This hides additionnal XML subfields, we don't need these info
203 delete $item->{'more_subfields_xml'};
205 # Display branch names instead of branch codes
206 $item->{'homebranchname'} = GetBranchName( $item->{'homebranch'} );
207 $item->{'holdingbranchname'} = GetBranchName( $item->{'holdingbranch'} );
210 # Hashref building...
211 $biblioitem->{'items'}->{'item'} = $items;
212 $biblioitem->{'reserves'}->{'reserve'} = $reserves[1];
213 $biblioitem->{'issues'}->{'issue'} = $issues;
215 map { $biblioitem->{$_} = encode_entities( $biblioitem->{$_}, '&' ) } grep( !/marcxml/, keys %$biblioitem );
217 push @records, $biblioitem;
220 return { record => \@records };
223 =head2 GetAuthorityRecords
225 Given a list of authority record identifiers, returns a list of record
226 objects that contain the authority records. The function user may request
227 a specific metadata schema for the record objects.
232 list of authority record identifiers
234 specifies the metadata schema of records to be returned, possible values:
239 sub GetAuthorityRecords {
242 # If the user asks for an unsupported schema, return an error code
243 if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
244 return { code => 'UnsupportedSchema' };
249 # Let's loop over the authority IDs
250 foreach my $authid ( split( / /, $cgi->param('id') ) ) {
252 # Get the record as XML string, or error code
253 my $record = GetAuthorityXML( $_ ) || "<record><code>RecordNotFound</code></record>";
254 $record =~ s/<\?xml(.*)\?>//go;
263 Looks up a patron in the ILS by an identifier, and returns the borrowernumber.
268 an identifier used to look up the patron in Koha
270 the type of the identifier, possible values:
281 # Get the borrower...
282 my $borrower = GetMember($cgi->param('id_type') => $cgi->param('id'));
283 if ( not $borrower->{'borrowernumber'} ) {
284 return { message => 'PatronNotFound' };
288 my $patron->{'id'} = $borrower->{'borrowernumber'};
289 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
291 # ...and return his ID
295 =head2 AuthenticatePatron
297 Authenticates a user's login credentials and returns the identifier for
302 - username (Required)
303 user's login identifier
304 - password (Required)
309 sub AuthenticatePatron {
312 # Check if borrower exists, using a C4::Auth function...
313 unless( checkpw( C4::Context->dbh, $cgi->param('username'), $cgi->param('password') ) ) {
314 return { code => 'PatronNotFound' };
318 my $borrower = GetMember( userid => $cgi->param('username') );
321 my $patron->{'id'} = $borrower->{'borrowernumber'};
323 # ... and return his ID
329 Returns specified information about the patron, based on options in the
330 request. This function can optionally return patron's contact information,
331 fine information, hold request information, and loan information.
335 - patron_id (Required)
337 - show_contact (Optional, default 1)
338 whether or not to return patron's contact information in the response
339 - show_fines (Optional, default 0)
340 whether or not to return fine information in the response
341 - show_holds (Optional, default 0)
342 whether or not to return hold request information in the response
343 - show_loans (Optional, default 0)
344 whether or not to return loan information request information in the response
352 my $borrowernumber = $cgi->param('patron_id');
353 my $borrower = GetMemberDetails( $borrowernumber );
354 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
356 # Cleaning the borrower hashref
357 $borrower->{'charges'} = $borrower->{'flags'}->{'CHARGES'}->{'amount'};
358 $borrower->{'branchname'} = GetBranchName( $borrower->{'branchcode'} );
359 delete $borrower->{'flags'};
360 delete $borrower->{'userid'};
361 delete $borrower->{'password'};
363 # Contact fields management
364 if ( $cgi->param('show_contact') eq "0" ) {
366 # Define contact fields
367 my @contactfields = (
368 'email', 'emailpro', 'fax', 'mobile', 'phone', 'phonepro',
369 'streetnumber', 'zipcode', 'city', 'streettype', 'B_address', 'B_city',
370 'B_email', 'B_phone', 'B_zipcode', 'address', 'address2', 'altcontactaddress1',
371 'altcontactaddress2', 'altcontactaddress3', 'altcontactfirstname', 'altcontactphone', 'altcontactsurname', 'altcontactzipcode'
375 foreach my $field (@contactfields) {
376 delete $borrower->{$field};
381 if ( $cgi->param('show_fines') eq "1" ) {
383 for ( my $i = 1 ; my @charge = getcharges( $borrowernumber, undef, $i ) ; $i++ ) {
384 push( @charges, @charge );
386 $borrower->{'fines'}->{'fine'} = \@charges;
389 # Reserves management
390 if ( $cgi->param('show_holds') eq "1" ) {
392 # Get borrower's reserves
393 my @reserves = GetReservesFromBorrowernumber( $borrowernumber, undef );
394 foreach my $reserve (@reserves) {
396 # Get additional informations
397 my $item = GetBiblioFromItemNumber( $reserve->{'itemnumber'}, undef );
398 my $branchname = GetBranchName( $reserve->{'branchcode'} );
400 # Remove unwanted fields
401 delete $item->{'marc'};
402 delete $item->{'marcxml'};
403 delete $item->{'more_subfields_xml'};
405 # Add additional fields
406 $reserve->{'item'} = $item;
407 $reserve->{'branchname'} = $branchname;
408 $reserve->{'title'} = ( GetBiblio( $reserve->{'biblionumber'} ) )[1]->{'title'};
410 $borrower->{'holds'}->{'hold'} = \@reserves;
414 if ( $cgi->param('show_loans') eq "1" ) {
415 my $issues = GetPendingIssues($borrowernumber);
416 $borrower->{'loans'}->{'loan'} = $issues;
422 =head2 GetPatronStatus
424 Returns a patron's status information.
428 - patron_id (Required)
433 sub GetPatronStatus {
437 my $borrowernumber = $cgi->param('patron_id');
438 my $borrower = GetMemberDetails( $borrowernumber );
439 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
443 type => $$borrower{categorycode},
445 expiry => $$borrower{dateexpiry},
451 Returns information about the services available on a particular item for
456 - patron_id (Required)
465 # Get the member, or return an error code if not found
466 my $borrowernumber = $cgi->param('patron_id');
467 my $borrower = GetMemberDetails( $borrowernumber );
468 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
470 # Get the item, or return an error code if not found
471 my $itemnumber = $cgi->param('item_id');
472 my $item = GetItem( $itemnumber );
473 return { code => 'RecordNotFound' } unless $$item{itemnumber};
477 # Reserve level management
478 my $biblionumber = $item->{'biblionumber'};
479 my $canbookbereserved = CanBookBeReserved( $borrower, $biblionumber );
480 if ($canbookbereserved) {
481 push @availablefor, 'title level hold';
482 my $canitembereserved = IsAvailableForItemLevelRequest($itemnumber);
483 if ($canitembereserved) {
484 push @availablefor, 'item level hold';
488 # Reserve cancellation management
489 my @reserves = GetReservesFromBorrowernumber( $borrowernumber, undef );
491 foreach my $reserve (@reserves) {
492 push @reserveditems, $reserve->{'itemnumber'};
494 if ( grep { $itemnumber eq $_ } @reserveditems ) {
495 push @availablefor, 'hold cancellation';
499 my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
501 push @availablefor, 'loan renewal';
505 my $barcode = $item->{'barcode'} || '';
506 $barcode = barcodedecode($barcode) if ( $barcode && C4::Context->preference('itemBarcodeInputFilter') );
508 my ( $issuingimpossible, $needsconfirmation ) = CanBookBeIssued( $borrower, $barcode );
510 # TODO push @availablefor, 'loan';
514 $out->{'AvailableFor'} = \@availablefor;
521 Extends the due date for a borrower's existing issue.
525 - patron_id (Required)
529 - desired_due_date (Required)
530 the date the patron would like the item returned by
537 # Get borrower infos or return an error code
538 my $borrowernumber = $cgi->param('patron_id');
539 my $borrower = GetMemberDetails( $borrowernumber );
540 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
542 # Get the item, or return an error code
543 my $itemnumber = $cgi->param('item_id');
544 my $item = GetItem( $itemnumber );
545 return { code => 'RecordNotFound' } unless $$item{itemnumber};
547 # Add renewal if possible
548 my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
549 if ( $renewal[0] ) { AddRenewal( $borrowernumber, $itemnumber ); }
551 my $issue = GetItemIssue($itemnumber);
555 $out->{'renewals'} = $issue->{'renewals'};
556 $out->{'date_due'} = $issue->{'date_due'};
557 $out->{'success'} = $renewal[0];
558 $out->{'error'} = $renewal[1];
565 Creates, for a borrower, a biblio-level hold reserve.
569 - patron_id (Required)
573 - request_location (Required)
574 IP address where the end user request is being placed
575 - pickup_location (Optional)
576 a branch code indicating the location to which to deliver the item for pickup
577 - needed_before_date (Optional)
578 date after which hold request is no longer needed
579 - pickup_expiry_date (Optional)
580 date after which item returned to shelf if item is not picked up
587 # Get the borrower or return an error code
588 my $borrowernumber = $cgi->param('patron_id');
589 my $borrower = GetMemberDetails( $borrowernumber );
590 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
592 # Get the biblio record, or return an error code
593 my $biblionumber = $cgi->param('bib_id');
594 my ( $count, $biblio ) = GetBiblio( $biblionumber );
595 return { code => 'RecordNotFound' } unless $$biblio{biblionumber};
597 my $title = $$biblio{title};
599 # Check if the biblio can be reserved
600 return { code => 'NotHoldable' } unless CanBookBeReserved( $borrowernumber, $biblionumber );
604 # Pickup branch management
605 if ( $cgi->param('pickup_location') ) {
606 $branch = $cgi->param('pickup_location');
607 my $branches = GetBranches;
608 return { code => 'LocationNotFound' } unless $$branches{$branch};
609 } else { # if the request provide no branch, use the borrower's branch
610 $branch = $$borrower{branchcode};
614 # $branch, $borrowernumber, $biblionumber, $constraint, $bibitems, $priority, $notes, $title, $checkitem, $found
615 AddReserve( $branch, $borrowernumber, $biblionumber, 'a', undef, 0, undef, $title, undef, undef );
619 $out->{'title'} = $title;
620 $out->{'pickup_location'} = GetBranchName($branch);
622 # TODO $out->{'date_available'} = '';
629 Creates, for a borrower, an item-level hold request on a specific item of
630 a bibliographic record in Koha.
634 - patron_id (Required)
640 - pickup_location (Optional)
641 a branch code indicating the location to which to deliver the item for pickup
642 - needed_before_date (Optional)
643 date after which hold request is no longer needed
644 - pickup_expiry_date (Optional)
645 date after which item returned to shelf if item is not picked up
652 # Get the borrower or return an error code
653 my $borrowernumber = $cgi->param('patron_id');
654 my $borrower = GetMemberDetails( $borrowernumber );
655 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
657 # Get the biblio or return an error code
658 my $biblionumber = $cgi->param('bib_id');
659 my ( $count, $biblio ) = GetBiblio($biblionumber);
660 return { code => 'RecordNotFound' } unless $$biblio{biblionumber};
662 my $title = $$biblio{title};
664 # Get the item or return an error code
665 my $itemnumber = $cgi->param('item_id');
666 my $item = GetItem( $itemnumber );
667 return { code => 'RecordNotFound' } unless $$item{itemnumber};
669 # If the biblio does not match the item, return an error code
670 return { code => 'RecordNotFound' } if $$item{biblionumber} ne $$biblio{biblionumber};
672 # Check for item disponibility
673 my $canitembereserved = CanItemBeReserved( $borrowernumber, $itemnumber );
674 my $canbookbereserved = CanBookBeReserved( $borrowernumber, $biblionumber );
675 return { code => 'NotHoldable' } unless $canbookbereserved and $canitembereserved;
679 # Pickup branch management
680 if ( $cgi->param('pickup_location') ) {
681 $branch = $cgi->param('pickup_location');
682 my $branches = GetBranches();
683 return { code => 'LocationNotFound' } unless $$branches{$branch};
684 } else { # if the request provide no branch, use the borrower's branch
685 $branch = $$borrower{branchcode};
692 $rank = '0' unless C4::Context->preference('ReservesNeedReturns');
693 if ( $item->{'holdingbranch'} eq $branch ) {
694 $found = 'W' unless C4::Context->preference('ReservesNeedReturns');
698 # $branch, $borrowernumber, $biblionumber, $constraint, $bibitems, $priority, $notes, $title, $checkitem, $found
699 AddReserve( $branch, $borrowernumber, $biblionumber, 'a', undef, $rank, undef, $title, $itemnumber, $found );
703 $out->{'pickup_location'} = GetBranchName($branch);
705 # TODO $out->{'date_available'} = '';
712 Cancels an active reserve request for the borrower.
716 - patron_id (Required)
726 # Get the borrower or return an error code
727 my $borrowernumber = $cgi->param('patron_id');
728 my $borrower = GetMemberDetails( $borrowernumber );
729 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
731 # Get the item or return an error code
732 my $itemnumber = $cgi->param('item_id');
733 my $item = GetItem( $itemnumber );
734 return { code => 'RecordNotFound' } unless $$item{itemnumber};
736 # Get borrower's reserves
737 my @reserves = GetReservesFromBorrowernumber( $borrowernumber, undef );
740 # ...and loop over it to build an array of reserved itemnumbers
741 foreach my $reserve (@reserves) {
742 push @reserveditems, $reserve->{'itemnumber'};
745 # if the item was not reserved by the borrower, returns an error code
746 return { code => 'NotCanceled' } unless any { $itemnumber eq $_ } @reserveditems;
749 CancelReserve( $itemnumber, undef, $borrowernumber );
751 return { code => 'Canceled' };