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 );
219 return { record => \@records };
222 =head2 GetAuthorityRecords
224 Given a list of authority record identifiers, returns a list of record
225 objects that contain the authority records. The function user may request
226 a specific metadata schema for the record objects.
231 list of authority record identifiers
233 specifies the metadata schema of records to be returned, possible values:
238 sub GetAuthorityRecords {
241 # If the user asks for an unsupported schema, return an error code
242 if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
243 return { code => 'UnsupportedSchema' };
248 # Let's loop over the authority IDs
249 foreach my $authid ( split( / /, $cgi->param('id') ) ) {
251 # Get the record as XML string, or error code
252 my $record = GetAuthorityXML( $_ ) || "<record><code>RecordNotFound</code></record>";
253 $record =~ s/<\?xml(.*)\?>//go;
262 Looks up a patron in the ILS by an identifier, and returns the borrowernumber.
267 an identifier used to look up the patron in Koha
269 the type of the identifier, possible values:
280 # Get the borrower...
281 my $borrower = GetMember($cgi->param('id_type') => $cgi->param('id'));
282 if ( not $borrower->{'borrowernumber'} ) {
283 return { message => 'PatronNotFound' };
287 my $patron->{'id'} = $borrower->{'borrowernumber'};
288 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
290 # ...and return his ID
294 =head2 AuthenticatePatron
296 Authenticates a user's login credentials and returns the identifier for
301 - username (Required)
302 user's login identifier
303 - password (Required)
308 sub AuthenticatePatron {
311 # Check if borrower exists, using a C4::Auth function...
312 unless( checkpw( C4::Context->dbh, $cgi->param('username'), $cgi->param('password') ) ) {
313 return { code => 'PatronNotFound' };
317 my $borrower = GetMember( userid => $cgi->param('username') );
320 my $patron->{'id'} = $borrower->{'borrowernumber'};
322 # ... and return his ID
328 Returns specified information about the patron, based on options in the
329 request. This function can optionally return patron's contact information,
330 fine information, hold request information, and loan information.
334 - patron_id (Required)
336 - show_contact (Optional, default 1)
337 whether or not to return patron's contact information in the response
338 - show_fines (Optional, default 0)
339 whether or not to return fine information in the response
340 - show_holds (Optional, default 0)
341 whether or not to return hold request information in the response
342 - show_loans (Optional, default 0)
343 whether or not to return loan information request information in the response
351 my $borrowernumber = $cgi->param('patron_id');
352 my $borrower = GetMemberDetails( $borrowernumber );
353 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
355 # Cleaning the borrower hashref
356 $borrower->{'charges'} = $borrower->{'flags'}->{'CHARGES'}->{'amount'};
357 $borrower->{'branchname'} = GetBranchName( $borrower->{'branchcode'} );
358 delete $borrower->{'flags'};
359 delete $borrower->{'userid'};
360 delete $borrower->{'password'};
362 # Contact fields management
363 if ( $cgi->param('show_contact') eq "0" ) {
365 # Define contact fields
366 my @contactfields = (
367 'email', 'emailpro', 'fax', 'mobile', 'phone', 'phonepro',
368 'streetnumber', 'zipcode', 'city', 'streettype', 'B_address', 'B_city',
369 'B_email', 'B_phone', 'B_zipcode', 'address', 'address2', 'altcontactaddress1',
370 'altcontactaddress2', 'altcontactaddress3', 'altcontactfirstname', 'altcontactphone', 'altcontactsurname', 'altcontactzipcode'
374 foreach my $field (@contactfields) {
375 delete $borrower->{$field};
380 if ( $cgi->param('show_fines') eq "1" ) {
382 for ( my $i = 1 ; my @charge = getcharges( $borrowernumber, undef, $i ) ; $i++ ) {
383 push( @charges, @charge );
385 $borrower->{'fines'}->{'fine'} = \@charges;
388 # Reserves management
389 if ( $cgi->param('show_holds') eq "1" ) {
391 # Get borrower's reserves
392 my @reserves = GetReservesFromBorrowernumber( $borrowernumber, undef );
393 foreach my $reserve (@reserves) {
395 # Get additional informations
396 my $item = GetBiblioFromItemNumber( $reserve->{'itemnumber'}, undef );
397 my $branchname = GetBranchName( $reserve->{'branchcode'} );
399 # Remove unwanted fields
400 delete $item->{'marc'};
401 delete $item->{'marcxml'};
402 delete $item->{'more_subfields_xml'};
404 # Add additional fields
405 $reserve->{'item'} = $item;
406 $reserve->{'branchname'} = $branchname;
407 $reserve->{'title'} = ( GetBiblio( $reserve->{'biblionumber'} ) )[1]->{'title'};
409 $borrower->{'holds'}->{'hold'} = \@reserves;
413 if ( $cgi->param('show_loans') eq "1" ) {
414 my $issues = GetPendingIssues($borrowernumber);
415 $borrower->{'loans'}->{'loan'} = $issues;
421 =head2 GetPatronStatus
423 Returns a patron's status information.
427 - patron_id (Required)
432 sub GetPatronStatus {
436 my $borrowernumber = $cgi->param('patron_id');
437 my $borrower = GetMemberDetails( $borrowernumber );
438 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
442 type => $$borrower{categorycode},
444 expiry => $$borrower{dateexpiry},
450 Returns information about the services available on a particular item for
455 - patron_id (Required)
464 # Get the member, or return an error code if not found
465 my $borrowernumber = $cgi->param('patron_id');
466 my $borrower = GetMemberDetails( $borrowernumber );
467 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
469 # Get the item, or return an error code if not found
470 my $itemnumber = $cgi->param('item_id');
471 my $item = GetItem( $itemnumber );
472 return { code => 'RecordNotFound' } unless $$item{itemnumber};
476 # Reserve level management
477 my $biblionumber = $item->{'biblionumber'};
478 my $canbookbereserved = CanBookBeReserved( $borrower, $biblionumber );
479 if ($canbookbereserved) {
480 push @availablefor, 'title level hold';
481 my $canitembereserved = IsAvailableForItemLevelRequest($itemnumber);
482 if ($canitembereserved) {
483 push @availablefor, 'item level hold';
487 # Reserve cancellation management
488 my @reserves = GetReservesFromBorrowernumber( $borrowernumber, undef );
490 foreach my $reserve (@reserves) {
491 push @reserveditems, $reserve->{'itemnumber'};
493 if ( grep { $itemnumber eq $_ } @reserveditems ) {
494 push @availablefor, 'hold cancellation';
498 my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
500 push @availablefor, 'loan renewal';
504 my $barcode = $item->{'barcode'} || '';
505 $barcode = barcodedecode($barcode) if ( $barcode && C4::Context->preference('itemBarcodeInputFilter') );
507 my ( $issuingimpossible, $needsconfirmation ) = CanBookBeIssued( $borrower, $barcode );
509 # TODO push @availablefor, 'loan';
513 $out->{'AvailableFor'} = \@availablefor;
520 Extends the due date for a borrower's existing issue.
524 - patron_id (Required)
528 - desired_due_date (Required)
529 the date the patron would like the item returned by
536 # Get borrower infos or return an error code
537 my $borrowernumber = $cgi->param('patron_id');
538 my $borrower = GetMemberDetails( $borrowernumber );
539 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
541 # Get the item, or return an error code
542 my $itemnumber = $cgi->param('item_id');
543 my $item = GetItem( $itemnumber );
544 return { code => 'RecordNotFound' } unless $$item{itemnumber};
546 # Add renewal if possible
547 my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
548 if ( $renewal[0] ) { AddRenewal( $borrowernumber, $itemnumber ); }
550 my $issue = GetItemIssue($itemnumber);
554 $out->{'renewals'} = $issue->{'renewals'};
555 $out->{'date_due'} = $issue->{'date_due'};
556 $out->{'success'} = $renewal[0];
557 $out->{'error'} = $renewal[1];
564 Creates, for a borrower, a biblio-level hold reserve.
568 - patron_id (Required)
572 - request_location (Required)
573 IP address where the end user request is being placed
574 - pickup_location (Optional)
575 a branch code indicating the location to which to deliver the item for pickup
576 - needed_before_date (Optional)
577 date after which hold request is no longer needed
578 - pickup_expiry_date (Optional)
579 date after which item returned to shelf if item is not picked up
586 # Get the borrower or return an error code
587 my $borrowernumber = $cgi->param('patron_id');
588 my $borrower = GetMemberDetails( $borrowernumber );
589 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
591 # Get the biblio record, or return an error code
592 my $biblionumber = $cgi->param('bib_id');
593 my ( $count, $biblio ) = GetBiblio( $biblionumber );
594 return { code => 'RecordNotFound' } unless $$biblio{biblionumber};
596 my $title = $$biblio{title};
598 # Check if the biblio can be reserved
599 return { code => 'NotHoldable' } unless CanBookBeReserved( $borrowernumber, $biblionumber );
603 # Pickup branch management
604 if ( $cgi->param('pickup_location') ) {
605 $branch = $cgi->param('pickup_location');
606 my $branches = GetBranches;
607 return { code => 'LocationNotFound' } unless $$branches{$branch};
608 } else { # if the request provide no branch, use the borrower's branch
609 $branch = $$borrower{branchcode};
613 # $branch, $borrowernumber, $biblionumber, $constraint, $bibitems, $priority, $notes, $title, $checkitem, $found
614 AddReserve( $branch, $borrowernumber, $biblionumber, 'a', undef, 0, undef, $title, undef, undef );
618 $out->{'title'} = $title;
619 $out->{'pickup_location'} = GetBranchName($branch);
621 # TODO $out->{'date_available'} = '';
628 Creates, for a borrower, an item-level hold request on a specific item of
629 a bibliographic record in Koha.
633 - patron_id (Required)
639 - pickup_location (Optional)
640 a branch code indicating the location to which to deliver the item for pickup
641 - needed_before_date (Optional)
642 date after which hold request is no longer needed
643 - pickup_expiry_date (Optional)
644 date after which item returned to shelf if item is not picked up
651 # Get the borrower or return an error code
652 my $borrowernumber = $cgi->param('patron_id');
653 my $borrower = GetMemberDetails( $borrowernumber );
654 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
656 # Get the biblio or return an error code
657 my $biblionumber = $cgi->param('bib_id');
658 my ( $count, $biblio ) = GetBiblio($biblionumber);
659 return { code => 'RecordNotFound' } unless $$biblio{biblionumber};
661 my $title = $$biblio{title};
663 # Get the item or return an error code
664 my $itemnumber = $cgi->param('item_id');
665 my $item = GetItem( $itemnumber );
666 return { code => 'RecordNotFound' } unless $$item{itemnumber};
668 # If the biblio does not match the item, return an error code
669 return { code => 'RecordNotFound' } if $$item{biblionumber} ne $$biblio{biblionumber};
671 # Check for item disponibility
672 my $canitembereserved = CanItemBeReserved( $borrowernumber, $itemnumber );
673 my $canbookbereserved = CanBookBeReserved( $borrowernumber, $biblionumber );
674 return { code => 'NotHoldable' } unless $canbookbereserved and $canitembereserved;
678 # Pickup branch management
679 if ( $cgi->param('pickup_location') ) {
680 $branch = $cgi->param('pickup_location');
681 my $branches = GetBranches();
682 return { code => 'LocationNotFound' } unless $$branches{$branch};
683 } else { # if the request provide no branch, use the borrower's branch
684 $branch = $$borrower{branchcode};
691 $rank = '0' unless C4::Context->preference('ReservesNeedReturns');
692 if ( $item->{'holdingbranch'} eq $branch ) {
693 $found = 'W' unless C4::Context->preference('ReservesNeedReturns');
697 # $branch, $borrowernumber, $biblionumber, $constraint, $bibitems, $priority, $notes, $title, $checkitem, $found
698 AddReserve( $branch, $borrowernumber, $biblionumber, 'a', undef, $rank, undef, $title, $itemnumber, $found );
702 $out->{'pickup_location'} = GetBranchName($branch);
704 # TODO $out->{'date_available'} = '';
711 Cancels an active reserve request for the borrower.
715 - patron_id (Required)
725 # Get the borrower or return an error code
726 my $borrowernumber = $cgi->param('patron_id');
727 my $borrower = GetMemberDetails( $borrowernumber );
728 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
730 # Get the item or return an error code
731 my $itemnumber = $cgi->param('item_id');
732 my $item = GetItem( $itemnumber );
733 return { code => 'RecordNotFound' } unless $$item{itemnumber};
735 # Get borrower's reserves
736 my @reserves = GetReservesFromBorrowernumber( $borrowernumber, undef );
739 # ...and loop over it to build an array of reserved itemnumbers
740 foreach my $reserve (@reserves) {
741 push @reserveditems, $reserve->{'itemnumber'};
744 # if the item was not reserved by the borrower, returns an error code
745 return { code => 'NotCanceled' } unless any { $itemnumber eq $_ } @reserveditems;
748 CancelReserve( $itemnumber, undef, $borrowernumber );
750 return { code => 'Canceled' };