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 CanBookBeReserved CanItemBeReserved IsAvailableForItemLevelRequest);
30 use C4::AuthoritiesMarc;
36 use C4::Members::Attributes qw(GetBorrowerAttributes);
46 C4::ILS-DI::Services - ILS-DI Services
50 Each function in this module represents an ILS-DI service.
51 They all takes a CGI instance as argument and most of them return a
52 hashref that will be printed by XML::Simple in opac/ilsdi.pl
56 use C4::ILSDI::Services;
62 $out = LookupPatron($cgi);
64 print CGI::header('text/xml');
69 xmldecl => '<?xml version="1.0" encoding="UTF-8" ?>',
70 RootName => 'LookupPatron',
77 =head2 GetAvailability
79 Given a set of biblionumbers or itemnumbers, returns a list with
80 availability of the items associated with the identifiers.
86 list of either biblionumbers or itemnumbers
88 =head3 id_type (Required)
90 defines the type of record identifier being used in the request,
96 =head3 return_type (Optional)
98 requests a particular level of detail in reporting availability,
104 =head3 return_fmt (Optional)
106 requests a particular format or set of formats in reporting
111 sub GetAvailability {
114 my $out = "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n";
115 $out .= "<dlf:collection\n";
116 $out .= " xmlns:dlf=\"http://diglib.org/ilsdi/1.1\"\n";
117 $out .= " xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n";
118 $out .= " xsi:schemaLocation=\"http://diglib.org/ilsdi/1.1\n";
119 $out .= " http://diglib.org/architectures/ilsdi/schemas/1.1/dlfexpanded.xsd\">\n";
121 foreach my $id ( split( / /, $cgi->param('id') ) ) {
122 if ( $cgi->param('id_type') eq "item" ) {
123 my ( $biblionumber, $status, $msg, $location ) = _availability($id);
125 $out .= " <dlf:record>\n";
126 $out .= " <dlf:bibliographic id=\"" . ( $biblionumber || $id ) . "\" />\n";
127 $out .= " <dlf:items>\n";
128 $out .= " <dlf:item id=\"" . $id . "\">\n";
129 $out .= " <dlf:simpleavailability>\n";
130 $out .= " <dlf:identifier>" . $id . "</dlf:identifier>\n";
131 $out .= " <dlf:availabilitystatus>" . $status . "</dlf:availabilitystatus>\n";
132 if ($msg) { $out .= " <dlf:availabilitymsg>" . $msg . "</dlf:availabilitymsg>\n"; }
133 if ($location) { $out .= " <dlf:location>" . $location . "</dlf:location>\n"; }
134 $out .= " </dlf:simpleavailability>\n";
135 $out .= " </dlf:item>\n";
136 $out .= " </dlf:items>\n";
137 $out .= " </dlf:record>\n";
141 my $items = GetItemnumbersForBiblio($id);
144 $out .= " <dlf:record>\n";
145 $out .= " <dlf:bibliographic id=\"" .$id. "\" />\n";
146 $out .= " <dlf:items>\n";
147 # We loop over the items to clean them
148 foreach my $itemnumber (@$items) {
149 my ( $biblionumber, $status, $msg, $location ) = _availability($itemnumber);
150 $out .= " <dlf:item id=\"" . $itemnumber . "\">\n";
151 $out .= " <dlf:simpleavailability>\n";
152 $out .= " <dlf:identifier>" . $itemnumber . "</dlf:identifier>\n";
153 $out .= " <dlf:availabilitystatus>" . $status . "</dlf:availabilitystatus>\n";
154 if ($msg) { $out .= " <dlf:availabilitymsg>" . $msg . "</dlf:availabilitymsg>\n"; }
155 if ($location) { $out .= " <dlf:location>" . $location . "</dlf:location>\n"; }
156 $out .= " </dlf:simpleavailability>\n";
157 $out .= " </dlf:item>\n";
160 $out .= " </dlf:items>\n";
161 $out .= " </dlf:record>\n";
164 $msg = "Error: could not retrieve availability for this ID";
168 $out .= "</dlf:collection>\n";
175 Given a list of biblionumbers, returns a list of record objects that
176 contain bibliographic information, as well as associated holdings and item
177 information. The caller may request a specific metadata schema for the
178 record objects to be returned.
180 This function behaves similarly to HarvestBibliographicRecords and
181 HarvestExpandedRecords in Data Aggregation, but allows quick, real time
182 lookup by bibliographic identifier.
184 You can use OAI-PMH ListRecords instead of this service.
189 list of system record identifiers
191 Defines the metadata schema in which the records are returned,
200 # Check if the schema is supported. For now, GetRecords only supports MARCXML
201 if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
202 return { code => 'UnsupportedSchema' };
207 # Loop over biblionumbers
208 foreach my $biblionumber ( split( / /, $cgi->param('id') ) ) {
210 # Get the biblioitem from the biblionumber
211 my $biblioitem = ( GetBiblioItemByBiblioNumber( $biblionumber, undef ) )[0];
212 if ( not $biblioitem->{'biblionumber'} ) {
213 $biblioitem->{code} = "RecordNotFound";
217 my $record = GetMarcBiblio($biblionumber, $embed_items);
219 $biblioitem->{marcxml} = $record->as_xml_record();
222 # Get most of the needed data
223 my $biblioitemnumber = $biblioitem->{'biblioitemnumber'};
224 my $biblio = Koha::Biblios->find( $biblionumber );
225 my $holds = $biblio->current_holds->unblessed;
226 my $issues = GetBiblioIssues($biblionumber);
227 my $items = GetItemsByBiblioitemnumber($biblioitemnumber);
229 # We loop over the items to clean them
230 foreach my $item (@$items) {
232 # This hides additionnal XML subfields, we don't need these info
233 delete $item->{'more_subfields_xml'};
235 # Display branch names instead of branch codes
236 my $home_library = Koha::Libraries->find( $item->{homebranch} );
237 my $holding_library = Koha::Libraries->find( $item->{holdingbranch} );
238 $item->{'homebranchname'} = $home_library ? $home_library->branchname : '';
239 $item->{'holdingbranchname'} = $holding_library ? $holding_library->branchname : '';
242 # Hashref building...
243 $biblioitem->{'items'}->{'item'} = $items;
244 $biblioitem->{'reserves'}->{'reserve'} = $holds;
245 $biblioitem->{'issues'}->{'issue'} = $issues;
247 push @records, $biblioitem;
250 return { record => \@records };
253 =head2 GetAuthorityRecords
255 Given a list of authority record identifiers, returns a list of record
256 objects that contain the authority records. The function user may request
257 a specific metadata schema for the record objects.
262 list of authority record identifiers
264 specifies the metadata schema of records to be returned, possible values:
269 sub GetAuthorityRecords {
272 # If the user asks for an unsupported schema, return an error code
273 if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
274 return { code => 'UnsupportedSchema' };
279 # Let's loop over the authority IDs
280 foreach my $authid ( split( / /, $cgi->param('id') ) ) {
282 # Get the record as XML string, or error code
283 push @records, GetAuthorityXML($authid) || { code => 'RecordNotFound' };
286 return { record => \@records };
291 Looks up a patron in the ILS by an identifier, and returns the borrowernumber.
296 an identifier used to look up the patron in Koha
298 the type of the identifier, possible values:
309 # Get the borrower...
310 my $borrower = GetMember($cgi->param('id_type') => $cgi->param('id'));
311 if ( not $borrower->{'borrowernumber'} ) {
312 return { message => 'PatronNotFound' };
316 my $patron->{'id'} = $borrower->{'borrowernumber'};
317 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
319 # ...and return his ID
323 =head2 AuthenticatePatron
325 Authenticates a user's login credentials and returns the identifier for
330 - username (Required)
331 user's login identifier (userid or cardnumber)
332 - password (Required)
337 sub AuthenticatePatron {
339 my $username = $cgi->param('username');
340 my $password = $cgi->param('password');
341 my ($status, $cardnumber, $userid) = C4::Auth::checkpw( C4::Context->dbh, $username, $password );
344 my $borrower = GetMember( cardnumber => $cardnumber );
345 my $patron->{'id'} = $borrower->{'borrowernumber'};
349 return { code => 'PatronNotFound' };
355 Returns specified information about the patron, based on options in the
356 request. This function can optionally return patron's contact information,
357 fine information, hold request information, and loan information.
361 - patron_id (Required)
363 - show_contact (Optional, default 1)
364 whether or not to return patron's contact information in the response
365 - show_fines (Optional, default 0)
366 whether or not to return fine information in the response
367 - show_holds (Optional, default 0)
368 whether or not to return hold request information in the response
369 - show_loans (Optional, default 0)
370 whether or not to return loan information request information in the response
378 my $borrowernumber = $cgi->param('patron_id');
379 my $borrower = GetMember( borrowernumber => $borrowernumber );
380 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
381 my $patron = Koha::Patrons->find( $borrowernumber );
383 # Cleaning the borrower hashref
384 my $flags = C4::Members::patronflags( $borrower );
385 $borrower->{'charges'} = $flags->{'CHARGES'}->{'amount'};
386 my $library = Koha::Libraries->find( $borrower->{branchcode} );
387 $borrower->{'branchname'} = $library ? $library->branchname : '';
388 delete $borrower->{'userid'};
389 delete $borrower->{'password'};
391 # Contact fields management
392 if ( defined $cgi->param('show_contact') && $cgi->param('show_contact') eq "0" ) {
394 # Define contact fields
395 my @contactfields = (
396 'email', 'emailpro', 'fax', 'mobile', 'phone', 'phonepro',
397 'streetnumber', 'zipcode', 'city', 'streettype', 'B_address', 'B_city',
398 'B_email', 'B_phone', 'B_zipcode', 'address', 'address2', 'altcontactaddress1',
399 'altcontactaddress2', 'altcontactaddress3', 'altcontactfirstname', 'altcontactphone', 'altcontactsurname', 'altcontactzipcode'
403 foreach my $field (@contactfields) {
404 delete $borrower->{$field};
409 if ( $cgi->param('show_fines') && $cgi->param('show_fines') eq "1" ) {
411 for ( my $i = 1 ; my @charge = getcharges( $borrowernumber, undef, $i ) ; $i++ ) {
412 push( @charges, @charge );
414 $borrower->{'fines'}->{'fine'} = \@charges;
417 # Reserves management
418 if ( $cgi->param('show_holds') && $cgi->param('show_holds') eq "1" ) {
420 # Get borrower's reserves
421 my $holds = $patron->holds;
422 while ( my $hold = $holds->next ) {
424 my $unblessed_hold = $hold->unblessed;
425 # Get additional informations
426 my $item = Koha::Items->find( $hold->itemnumber );
427 my $biblio = $item->biblio;
428 my $biblioitem = $biblio->biblioitem;
429 my $library = Koha::Libraries->find( $hold->branchcode ); # Should $hold->get_library
430 my $branchname = $library ? $library->branchname : '';
432 # Remove unwanted fields
433 $item = $item->unblessed;
434 delete $item->{'more_subfields_xml'};
435 $biblio = $biblio->unblessed;
436 $biblioitem = $biblioitem->unblessed;
438 # Add additional fields
439 $unblessed_hold->{item} = { %$item, %$biblio, %$biblioitem };
440 $unblessed_hold->{branchname} = $branchname;
441 $unblessed_hold->{title} = GetBiblio( $hold->biblionumber )->{'title'}; # Should be $hold->get_biblio
443 push @{ $borrower->{holds}{hold} }, $unblessed_hold;
448 if ( $cgi->param('show_loans') && $cgi->param('show_loans') eq "1" ) {
449 my $issues = GetPendingIssues($borrowernumber);
450 foreach my $issue ( @$issues ){
451 $issue->{'issuedate'} = $issue->{'issuedate'}->strftime('%Y-%m-%d %H:%M');
452 $issue->{'date_due'} = $issue->{'date_due'}->strftime('%Y-%m-%d %H:%M');
454 $borrower->{'loans'}->{'loan'} = $issues;
457 if ( $cgi->param('show_attributes') eq "1" ) {
458 my $attrs = GetBorrowerAttributes( $borrowernumber, 0, 1 );
459 $borrower->{'attributes'} = $attrs;
465 =head2 GetPatronStatus
467 Returns a patron's status information.
471 - patron_id (Required)
476 sub GetPatronStatus {
480 my $borrowernumber = $cgi->param('patron_id');
481 my $borrower = GetMember( borrowernumber => $borrowernumber );
482 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
486 type => $$borrower{categorycode},
488 expiry => $$borrower{dateexpiry},
494 Returns information about the services available on a particular item for
499 - patron_id (Required)
509 # Get the member, or return an error code if not found
510 my $borrowernumber = $cgi->param('patron_id');
511 my $borrower = GetMember( borrowernumber => $borrowernumber );
512 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
514 my $patron = Koha::Patrons->find( $borrowernumber );
516 # Get the item, or return an error code if not found
517 my $itemnumber = $cgi->param('item_id');
518 my $item = GetItem( $itemnumber );
519 return { code => 'RecordNotFound' } unless $$item{itemnumber};
523 # Reserve level management
524 my $biblionumber = $item->{'biblionumber'};
525 my $canbookbereserved = CanBookBeReserved( $borrower, $biblionumber );
526 if ($canbookbereserved eq 'OK') {
527 push @availablefor, 'title level hold';
528 my $canitembereserved = IsAvailableForItemLevelRequest($item, $borrower);
529 if ($canitembereserved) {
530 push @availablefor, 'item level hold';
534 # Reserve cancellation management
535 my $holds = $patron->holds;
537 while ( my $hold = $holds->next ) { # FIXME This could be improved
538 push @reserveditems, $hold->itemnumber;
540 if ( grep { $itemnumber eq $_ } @reserveditems ) {
541 push @availablefor, 'hold cancellation';
545 my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
547 push @availablefor, 'loan renewal';
551 my $barcode = $item->{'barcode'} || '';
552 $barcode = barcodedecode($barcode) if ( $barcode && C4::Context->preference('itemBarcodeInputFilter') );
554 my ( $issuingimpossible, $needsconfirmation ) = CanBookBeIssued( $borrower, $barcode );
556 # TODO push @availablefor, 'loan';
560 $out->{'AvailableFor'} = \@availablefor;
567 Extends the due date for a borrower's existing issue.
571 - patron_id (Required)
575 - desired_due_date (Required)
576 the date the patron would like the item returned by
583 # Get borrower infos or return an error code
584 my $borrowernumber = $cgi->param('patron_id');
585 my $borrower = GetMember( borrowernumber => $borrowernumber );
586 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
588 # Get the item, or return an error code
589 my $itemnumber = $cgi->param('item_id');
590 my $item = GetItem( $itemnumber );
591 return { code => 'RecordNotFound' } unless $$item{itemnumber};
593 # Add renewal if possible
594 my @renewal = CanBookBeRenewed( $borrowernumber, $itemnumber );
595 if ( $renewal[0] ) { AddRenewal( $borrowernumber, $itemnumber ); }
597 my $issue = Koha::Checkouts->find( { itemnumber => $itemnumber } ) or return; # FIXME should be handled
601 $out->{'renewals'} = $issue->renewals;
602 $out->{date_due} = dt_from_string($issue->date_due)->strftime('%Y-%m-%d %H:%S');
603 $out->{'success'} = $renewal[0];
604 $out->{'error'} = $renewal[1];
611 Creates, for a borrower, a biblio-level hold reserve.
615 - patron_id (Required)
619 - request_location (Required)
620 IP address where the end user request is being placed
621 - pickup_location (Optional)
622 a branch code indicating the location to which to deliver the item for pickup
623 - needed_before_date (Optional)
624 date after which hold request is no longer needed
625 - pickup_expiry_date (Optional)
626 date after which item returned to shelf if item is not picked up
633 # Get the borrower or return an error code
634 my $borrowernumber = $cgi->param('patron_id');
635 my $borrower = GetMember( borrowernumber => $borrowernumber );
636 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
638 # Get the biblio record, or return an error code
639 my $biblionumber = $cgi->param('bib_id');
640 my $biblio = GetBiblio( $biblionumber );
641 return { code => 'RecordNotFound' } unless $$biblio{biblionumber};
643 my $title = $$biblio{title};
645 # Check if the biblio can be reserved
646 return { code => 'NotHoldable' } unless CanBookBeReserved( $borrowernumber, $biblionumber ) eq 'OK';
650 # Pickup branch management
651 if ( $cgi->param('pickup_location') ) {
652 $branch = $cgi->param('pickup_location');
653 return { code => 'LocationNotFound' } unless Koha::Libraries->find($branch);
654 } else { # if the request provide no branch, use the borrower's branch
655 $branch = $$borrower{branchcode};
659 # $branch, $borrowernumber, $biblionumber,
660 # $constraint, $bibitems, $priority, $resdate, $expdate, $notes,
661 # $title, $checkitem, $found
662 my $priority= C4::Reserves::CalculatePriority( $biblionumber );
663 AddReserve( $branch, $borrowernumber, $biblionumber, undef, $priority, undef, undef, undef, $title, undef, undef );
667 $out->{'title'} = $title;
668 my $library = Koha::Libraries->find( $branch );
669 $out->{'pickup_location'} = $library ? $library->branchname : '';
671 # TODO $out->{'date_available'} = '';
678 Creates, for a borrower, an item-level hold request on a specific item of
679 a bibliographic record in Koha.
683 - patron_id (Required)
689 - pickup_location (Optional)
690 a branch code indicating the location to which to deliver the item for pickup
691 - needed_before_date (Optional)
692 date after which hold request is no longer needed
693 - pickup_expiry_date (Optional)
694 date after which item returned to shelf if item is not picked up
701 # Get the borrower or return an error code
702 my $borrowernumber = $cgi->param('patron_id');
703 my $borrower = GetMember( borrowernumber => $borrowernumber );
704 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
706 # Get the biblio or return an error code
707 my $biblionumber = $cgi->param('bib_id');
708 my $biblio = GetBiblio($biblionumber);
709 return { code => 'RecordNotFound' } unless $$biblio{biblionumber};
711 my $title = $$biblio{title};
713 # Get the item or return an error code
714 my $itemnumber = $cgi->param('item_id');
715 my $item = GetItem( $itemnumber );
716 return { code => 'RecordNotFound' } unless $$item{itemnumber};
718 # If the biblio does not match the item, return an error code
719 return { code => 'RecordNotFound' } if $$item{biblionumber} ne $$biblio{biblionumber};
721 # Check for item disponibility
722 my $canitembereserved = C4::Reserves::CanItemBeReserved( $borrowernumber, $itemnumber );
723 my $canbookbereserved = C4::Reserves::CanBookBeReserved( $borrowernumber, $biblionumber );
724 return { code => 'NotHoldable' } unless $canbookbereserved eq 'OK' and $canitembereserved eq 'OK';
726 # Pickup branch management
728 if ( $cgi->param('pickup_location') ) {
729 $branch = $cgi->param('pickup_location');
730 return { code => 'LocationNotFound' } unless Koha::Libraries->find($branch);
731 } else { # if the request provide no branch, use the borrower's branch
732 $branch = $$borrower{branchcode};
736 # $branch, $borrowernumber, $biblionumber,
737 # $constraint, $bibitems, $priority, $resdate, $expdate, $notes,
738 # $title, $checkitem, $found
739 my $priority= C4::Reserves::CalculatePriority( $biblionumber );
740 AddReserve( $branch, $borrowernumber, $biblionumber, undef, $priority, undef, undef, undef, $title, $itemnumber, undef );
744 my $library = Koha::Libraries->find( $branch );
745 $out->{'pickup_location'} = $library ? $library->branchname : '';
747 # TODO $out->{'date_available'} = '';
754 Cancels an active reserve request for the borrower.
758 - patron_id (Required)
768 # Get the borrower or return an error code
769 my $borrowernumber = $cgi->param('patron_id');
770 my $borrower = GetMember( borrowernumber => $borrowernumber );
771 return { code => 'PatronNotFound' } unless $$borrower{borrowernumber};
773 # Get the reserve or return an error code
774 my $reserve_id = $cgi->param('item_id');
775 my $reserve = C4::Reserves::GetReserve($reserve_id);
776 return { code => 'RecordNotFound' } unless $reserve;
777 return { code => 'RecordNotFound' } unless ($reserve->{borrowernumber} == $borrowernumber);
779 C4::Reserves::CancelReserve({reserve_id => $reserve_id});
781 return { code => 'Canceled' };
786 Returns, for an itemnumber, an array containing availability information.
788 my ($biblionumber, $status, $msg, $location) = _availability($id);
793 my ($itemnumber) = @_;
794 my $item = GetItem( $itemnumber, undef, undef );
796 if ( not $item->{'itemnumber'} ) {
797 return ( undef, 'unknown', 'Error: could not retrieve availability for this ID', undef );
800 my $biblionumber = $item->{'biblioitemnumber'};
801 my $library = Koha::Libraries->find( $item->{holdingbranch} );
802 my $location = $library ? $library->branchname : '';
804 if ( $item->{'notforloan'} ) {
805 return ( $biblionumber, 'not available', 'Not for loan', $location );
806 } elsif ( $item->{'onloan'} ) {
807 return ( $biblionumber, 'not available', 'Checked out', $location );
808 } elsif ( $item->{'itemlost'} ) {
809 return ( $biblionumber, 'not available', 'Item lost', $location );
810 } elsif ( $item->{'withdrawn'} ) {
811 return ( $biblionumber, 'not available', 'Item withdrawn', $location );
812 } elsif ( $item->{'damaged'} ) {
813 return ( $biblionumber, 'not available', 'Item damaged', $location );
815 return ( $biblionumber, 'available', undef, $location );