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 CanBookBeReserved CanItemBeReserved);
31 use C4::AuthoritiesMarc;
32 use C4::ILSDI::Utility;
41 C4::ILS-DI::Services - ILS-DI Services
45 Each function in this module represents an ILS-DI service.
46 They all takes a CGI instance as argument and most of them return a
47 hashref that will be printed by XML::Simple in opac/ilsdi.pl
51 use C4::ILSDI::Services;
57 $out = LookupPatron($cgi);
59 print CGI::header('text/xml');
64 xmldecl => '<?xml version="1.0" encoding="UTF-8" ?>',
65 RootName => 'LookupPatron',
72 =head2 GetAvailability
74 Given a set of biblionumbers or itemnumbers, returns a list with
75 availability of the items associated with the identifiers.
81 list of either biblionumbers or itemnumbers
83 =head3 id_type (Required)
85 defines the type of record identifier being used in the request,
91 =head3 return_type (Optional)
93 requests a particular level of detail in reporting availability,
99 =head3 return_fmt (Optional)
101 requests a particular format or set of formats in reporting
106 sub GetAvailability {
109 my $out = "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n";
110 $out .= "<dlf:collection\n";
111 $out .= " xmlns:dlf=\"http://diglib.org/ilsdi/1.1\"\n";
112 $out .= " xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n";
113 $out .= " xsi:schemaLocation=\"http://diglib.org/ilsdi/1.1\n";
114 $out .= " http://diglib.org/architectures/ilsdi/schemas/1.1/dlfexpanded.xsd\">\n";
116 foreach my $id ( split( / /, $cgi->param('id') ) ) {
117 if ( $cgi->param('id_type') eq "item" ) {
118 my ( $biblionumber, $status, $msg, $location ) = Availability($id);
120 $out .= " <dlf:record>\n";
121 $out .= " <dlf:bibliographic id=\"" . ( $biblionumber || $id ) . "\" />\n";
122 $out .= " <dlf:items>\n";
123 $out .= " <dlf:item id=\"" . $id . "\">\n";
124 $out .= " <dlf:simpleavailability>\n";
125 $out .= " <dlf:identifier>" . $id . "</dlf:identifier>\n";
126 $out .= " <dlf:availabilitystatus>" . $status . "</dlf:availabilitystatus>\n";
127 if ($msg) { $out .= " <dlf:availabilitymsg>" . $msg . "</dlf:availabilitymsg>\n"; }
128 if ($location) { $out .= " <dlf:location>" . $location . "</dlf:location>\n"; }
129 $out .= " </dlf:simpleavailability>\n";
130 $out .= " </dlf:item>\n";
131 $out .= " </dlf:items>\n";
132 $out .= " </dlf:record>\n";
136 my $biblioitem = ( GetBiblioItemByBiblioNumber( $id, undef ) )[0];
141 $msg = "Error: could not retrieve availability for this ID";
143 $out .= " <dlf:record>\n";
144 $out .= " <dlf:bibliographic id=\"" . $id . "\" />\n";
145 $out .= " <dlf:simpleavailability>\n";
146 $out .= " <dlf:identifier>" . $id . "</dlf:identifier>\n";
147 $out .= " <dlf:availabilitystatus>" . $status . "</dlf:availabilitystatus>\n";
148 $out .= " <dlf:availabilitymsg>" . $msg . "</dlf:availabilitymsg>\n";
149 $out .= " </dlf:simpleavailability>\n";
150 $out .= " </dlf:record>\n";
153 $out .= "</dlf:collection>\n";
160 Given a list of biblionumbers, returns a list of record objects that
161 contain bibliographic information, as well as associated holdings and item
162 information. The caller may request a specific metadata schema for the
163 record objects to be returned.
165 This function behaves similarly to HarvestBibliographicRecords and
166 HarvestExpandedRecords in Data Aggregation, but allows quick, real time
167 lookup by bibliographic identifier.
169 You can use OAI-PMH ListRecords instead of this service.
174 list of system record identifiers
176 Defines the metadata schema in which the records are returned,
185 # Check if the schema is supported. For now, GetRecords only supports MARCXML
186 if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
187 return { code => 'UnsupportedSchema' };
192 # Loop over biblionumbers
193 foreach my $biblionumber ( split( / /, $cgi->param('id') ) ) {
195 # Get the biblioitem from the biblionumber
196 my $biblioitem = ( GetBiblioItemByBiblioNumber( $biblionumber, undef ) )[0];
197 if ( not $biblioitem->{'biblionumber'} ) {
198 $biblioitem->{code} = "RecordNotFound";
202 my $record = GetMarcBiblio($biblionumber, $embed_items);
204 $biblioitem->{marcxml} = $record->as_xml_record();
207 # We don't want MARC to be displayed
208 delete $biblioitem->{'marc'};
210 # Get most of the needed data
211 my $biblioitemnumber = $biblioitem->{'biblioitemnumber'};
212 my @reserves = GetReservesFromBiblionumber( $biblionumber, undef, undef );
213 my $issues = GetBiblioIssues($biblionumber);
214 my $items = GetItemsByBiblioitemnumber($biblioitemnumber);
216 # We loop over the items to clean them
217 foreach my $item (@$items) {
219 # This hides additionnal XML subfields, we don't need these info
220 delete $item->{'more_subfields_xml'};
222 # Display branch names instead of branch codes
223 $item->{'homebranchname'} = GetBranchName( $item->{'homebranch'} );
224 $item->{'holdingbranchname'} = GetBranchName( $item->{'holdingbranch'} );
227 # Hashref building...
228 $biblioitem->{'items'}->{'item'} = $items;
229 $biblioitem->{'reserves'}->{'reserve'} = $reserves[1];
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
317 - password (Required)
322 sub AuthenticatePatron {
325 # Check if borrower exists, using a C4::Auth function...
326 unless( C4::Auth::checkpw( C4::Context->dbh, $cgi->param('username'), $cgi->param('password') ) ) {
327 return { code => 'PatronNotFound' };
331 my $borrower = GetMember( userid => $cgi->param('username') );
334 my $patron->{'id'} = $borrower->{'borrowernumber'};
336 # ... and return his ID
342 Returns specified information about the patron, based on options in the
343 request. This function can optionally return patron's contact information,
344 fine information, hold request information, and loan information.
348 - patron_id (Required)
350 - show_contact (Optional, default 1)
351 whether or not to return patron's contact information in the response
352 - show_fines (Optional, default 0)
353 whether or not to return fine information in the response
354 - show_holds (Optional, default 0)
355 whether or not to return hold request information in the response
356 - show_loans (Optional, default 0)
357 whether or not to return loan information request information in the response
365 my $borrowernumber = $cgi->param('patron_id');
366 my $borrower = GetMemberDetails( $borrowernumber );
367 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
369 # Cleaning the borrower hashref
370 $borrower->{'charges'} = $borrower->{'flags'}->{'CHARGES'}->{'amount'};
371 $borrower->{'branchname'} = GetBranchName( $borrower->{'branchcode'} );
372 delete $borrower->{'flags'};
373 delete $borrower->{'userid'};
374 delete $borrower->{'password'};
376 # Contact fields management
377 if ( $cgi->param('show_contact') eq "0" ) {
379 # Define contact fields
380 my @contactfields = (
381 'email', 'emailpro', 'fax', 'mobile', 'phone', 'phonepro',
382 'streetnumber', 'zipcode', 'city', 'streettype', 'B_address', 'B_city',
383 'B_email', 'B_phone', 'B_zipcode', 'address', 'address2', 'altcontactaddress1',
384 'altcontactaddress2', 'altcontactaddress3', 'altcontactfirstname', 'altcontactphone', 'altcontactsurname', 'altcontactzipcode'
388 foreach my $field (@contactfields) {
389 delete $borrower->{$field};
394 if ( $cgi->param('show_fines') eq "1" ) {
396 for ( my $i = 1 ; my @charge = getcharges( $borrowernumber, undef, $i ) ; $i++ ) {
397 push( @charges, @charge );
399 $borrower->{'fines'}->{'fine'} = \@charges;
402 # Reserves management
403 if ( $cgi->param('show_holds') eq "1" ) {
405 # Get borrower's reserves
406 my @reserves = GetReservesFromBorrowernumber( $borrowernumber, undef );
407 foreach my $reserve (@reserves) {
409 # Get additional informations
410 my $item = GetBiblioFromItemNumber( $reserve->{'itemnumber'}, undef );
411 my $branchname = GetBranchName( $reserve->{'branchcode'} );
413 # Remove unwanted fields
414 delete $item->{'marc'};
415 delete $item->{'marcxml'};
416 delete $item->{'more_subfields_xml'};
418 # Add additional fields
419 $reserve->{'item'} = $item;
420 $reserve->{'branchname'} = $branchname;
421 $reserve->{'title'} = GetBiblio( $reserve->{'biblionumber'} )->{'title'};
423 $borrower->{'holds'}->{'hold'} = \@reserves;
427 if ( $cgi->param('show_loans') eq "1" ) {
428 my $issues = GetPendingIssues($borrowernumber);
429 foreach my $issue ( @$issues ){
430 $issue->{'issuedate'} = $issue->{'issuedate'}->strftime('%Y-%m-%d %H:%M');
431 $issue->{'date_due'} = $issue->{'date_due'}->strftime('%Y-%m-%d %H:%M');
433 $borrower->{'loans'}->{'loan'} = $issues;
439 =head2 GetPatronStatus
441 Returns a patron's status information.
445 - patron_id (Required)
450 sub GetPatronStatus {
454 my $borrowernumber = $cgi->param('patron_id');
455 my $borrower = GetMemberDetails( $borrowernumber );
456 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
460 type => $$borrower{categorycode},
462 expiry => $$borrower{dateexpiry},
468 Returns information about the services available on a particular item for
473 - patron_id (Required)
482 # Get the member, or return an error code if not found
483 my $borrowernumber = $cgi->param('patron_id');
484 my $borrower = GetMemberDetails( $borrowernumber );
485 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
487 # Get the item, or return an error code if not found
488 my $itemnumber = $cgi->param('item_id');
489 my $item = GetItem( $itemnumber );
490 return { code => 'RecordNotFound' } unless $$item{itemnumber};
494 # Reserve level management
495 my $biblionumber = $item->{'biblionumber'};
496 my $canbookbereserved = CanBookBeReserved( $borrower, $biblionumber );
497 if ($canbookbereserved) {
498 push @availablefor, 'title level hold';
499 my $canitembereserved = IsAvailableForItemLevelRequest($itemnumber);
500 if ($canitembereserved) {
501 push @availablefor, 'item level hold';
505 # Reserve cancellation management
506 my @reserves = GetReservesFromBorrowernumber( $borrowernumber, undef );
508 foreach my $reserve (@reserves) {
509 push @reserveditems, $reserve->{'itemnumber'};
511 if ( grep { $itemnumber eq $_ } @reserveditems ) {
512 push @availablefor, 'hold cancellation';
516 my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
518 push @availablefor, 'loan renewal';
522 my $barcode = $item->{'barcode'} || '';
523 $barcode = barcodedecode($barcode) if ( $barcode && C4::Context->preference('itemBarcodeInputFilter') );
525 my ( $issuingimpossible, $needsconfirmation ) = CanBookBeIssued( $borrower, $barcode );
527 # TODO push @availablefor, 'loan';
531 $out->{'AvailableFor'} = \@availablefor;
538 Extends the due date for a borrower's existing issue.
542 - patron_id (Required)
546 - desired_due_date (Required)
547 the date the patron would like the item returned by
554 # Get borrower infos or return an error code
555 my $borrowernumber = $cgi->param('patron_id');
556 my $borrower = GetMemberDetails( $borrowernumber );
557 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
559 # Get the item, or return an error code
560 my $itemnumber = $cgi->param('item_id');
561 my $item = GetItem( $itemnumber );
562 return { code => 'RecordNotFound' } unless $$item{itemnumber};
564 # Add renewal if possible
565 my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
566 if ( $renewal[0] ) { AddRenewal( $borrowernumber, $itemnumber ); }
568 my $issue = GetItemIssue($itemnumber);
572 $out->{'renewals'} = $issue->{'renewals'};
573 $out->{date_due} = $issue->{date_due}->strftime('%Y-%m-%d %H:%S');
574 $out->{'success'} = $renewal[0];
575 $out->{'error'} = $renewal[1];
582 Creates, for a borrower, a biblio-level hold reserve.
586 - patron_id (Required)
590 - request_location (Required)
591 IP address where the end user request is being placed
592 - pickup_location (Optional)
593 a branch code indicating the location to which to deliver the item for pickup
594 - needed_before_date (Optional)
595 date after which hold request is no longer needed
596 - pickup_expiry_date (Optional)
597 date after which item returned to shelf if item is not picked up
604 # Get the borrower or return an error code
605 my $borrowernumber = $cgi->param('patron_id');
606 my $borrower = GetMemberDetails( $borrowernumber );
607 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
609 # Get the biblio record, or return an error code
610 my $biblionumber = $cgi->param('bib_id');
611 my $biblio = GetBiblio( $biblionumber );
612 return { code => 'RecordNotFound' } unless $$biblio{biblionumber};
614 my $title = $$biblio{title};
616 # Check if the biblio can be reserved
617 return { code => 'NotHoldable' } unless CanBookBeReserved( $borrowernumber, $biblionumber );
621 # Pickup branch management
622 if ( $cgi->param('pickup_location') ) {
623 $branch = $cgi->param('pickup_location');
624 my $branches = GetBranches;
625 return { code => 'LocationNotFound' } unless $$branches{$branch};
626 } else { # if the request provide no branch, use the borrower's branch
627 $branch = $$borrower{branchcode};
631 # $branch, $borrowernumber, $biblionumber, $constraint, $bibitems, $priority, $notes, $title, $checkitem, $found
632 AddReserve( $branch, $borrowernumber, $biblionumber, 'a', undef, 0, undef, $title, undef, undef );
636 $out->{'title'} = $title;
637 $out->{'pickup_location'} = GetBranchName($branch);
639 # TODO $out->{'date_available'} = '';
646 Creates, for a borrower, an item-level hold request on a specific item of
647 a bibliographic record in Koha.
651 - patron_id (Required)
657 - pickup_location (Optional)
658 a branch code indicating the location to which to deliver the item for pickup
659 - needed_before_date (Optional)
660 date after which hold request is no longer needed
661 - pickup_expiry_date (Optional)
662 date after which item returned to shelf if item is not picked up
669 # Get the borrower or return an error code
670 my $borrowernumber = $cgi->param('patron_id');
671 my $borrower = GetMemberDetails( $borrowernumber );
672 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
674 # Get the biblio or return an error code
675 my $biblionumber = $cgi->param('bib_id');
676 my $biblio = GetBiblio($biblionumber);
677 return { code => 'RecordNotFound' } unless $$biblio{biblionumber};
679 my $title = $$biblio{title};
681 # Get the item or return an error code
682 my $itemnumber = $cgi->param('item_id');
683 my $item = GetItem( $itemnumber );
684 return { code => 'RecordNotFound' } unless $$item{itemnumber};
686 # If the biblio does not match the item, return an error code
687 return { code => 'RecordNotFound' } if $$item{biblionumber} ne $$biblio{biblionumber};
689 # Check for item disponibility
690 my $canitembereserved = C4::Reserves::CanItemBeReserved( $borrowernumber, $itemnumber );
691 my $canbookbereserved = C4::Reserves::CanBookBeReserved( $borrowernumber, $biblionumber );
692 return { code => 'NotHoldable' } unless $canbookbereserved and $canitembereserved;
696 # Pickup branch management
697 if ( $cgi->param('pickup_location') ) {
698 $branch = $cgi->param('pickup_location');
699 my $branches = GetBranches();
700 return { code => 'LocationNotFound' } unless $$branches{$branch};
701 } else { # if the request provide no branch, use the borrower's branch
702 $branch = $$borrower{branchcode};
709 $rank = '0' unless C4::Context->preference('ReservesNeedReturns');
710 if ( $item->{'holdingbranch'} eq $branch ) {
711 $found = 'W' unless C4::Context->preference('ReservesNeedReturns');
715 # $branch,$borrowernumber,$biblionumber,$constraint,$bibitems,$priority,$resdate,$expdate,$notes,$title,$checkitem,$found
716 AddReserve( $branch, $borrowernumber, $biblionumber, 'a', undef, $rank, '', '', '', $title, $itemnumber, $found );
720 $out->{'pickup_location'} = GetBranchName($branch);
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 = GetMemberDetails( $borrowernumber );
746 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
748 # Get the item or return an error code
749 my $itemnumber = $cgi->param('item_id');
750 my $item = GetItem( $itemnumber );
751 return { code => 'RecordNotFound' } unless $$item{itemnumber};
753 # Get borrower's reserves
754 my @reserves = GetReservesFromBorrowernumber( $borrowernumber, undef );
757 # ...and loop over it to build an array of reserved itemnumbers
758 foreach my $reserve (@reserves) {
759 push @reserveditems, $reserve->{'itemnumber'};
762 # if the item was not reserved by the borrower, returns an error code
763 return { code => 'NotCanceled' } unless any { $itemnumber eq $_ } @reserveditems;
766 CancelReserve({ itemnumber => $itemnumber, borrowernumber => $borrowernumber });
768 return { code => 'Canceled' };