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);
47 C4::ILS-DI::Services - ILS-DI Services
51 Each function in this module represents an ILS-DI service.
52 They all takes a CGI instance as argument and most of them return a
53 hashref that will be printed by XML::Simple in opac/ilsdi.pl
57 use C4::ILSDI::Services;
63 $out = LookupPatron($cgi);
65 print CGI::header('text/xml');
70 xmldecl => '<?xml version="1.0" encoding="UTF-8" ?>',
71 RootName => 'LookupPatron',
78 =head2 GetAvailability
80 Given a set of biblionumbers or itemnumbers, returns a list with
81 availability of the items associated with the identifiers.
87 list of either biblionumbers or itemnumbers
89 =head3 id_type (Required)
91 defines the type of record identifier being used in the request,
97 =head3 return_type (Optional)
99 requests a particular level of detail in reporting availability,
105 =head3 return_fmt (Optional)
107 requests a particular format or set of formats in reporting
112 sub GetAvailability
{
115 my $out = "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n";
116 $out .= "<dlf:collection\n";
117 $out .= " xmlns:dlf=\"http://diglib.org/ilsdi/1.1\"\n";
118 $out .= " xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n";
119 $out .= " xsi:schemaLocation=\"http://diglib.org/ilsdi/1.1\n";
120 $out .= " http://diglib.org/architectures/ilsdi/schemas/1.1/dlfexpanded.xsd\">\n";
122 foreach my $id ( split( / /, $cgi->param('id') ) ) {
123 if ( $cgi->param('id_type') eq "item" ) {
124 my ( $biblionumber, $status, $msg, $location ) = _availability
($id);
126 $out .= " <dlf:record>\n";
127 $out .= " <dlf:bibliographic id=\"" . ( $biblionumber || $id ) . "\" />\n";
128 $out .= " <dlf:items>\n";
129 $out .= " <dlf:item id=\"" . $id . "\">\n";
130 $out .= " <dlf:simpleavailability>\n";
131 $out .= " <dlf:identifier>" . $id . "</dlf:identifier>\n";
132 $out .= " <dlf:availabilitystatus>" . $status . "</dlf:availabilitystatus>\n";
133 if ($msg) { $out .= " <dlf:availabilitymsg>" . $msg . "</dlf:availabilitymsg>\n"; }
134 if ($location) { $out .= " <dlf:location>" . $location . "</dlf:location>\n"; }
135 $out .= " </dlf:simpleavailability>\n";
136 $out .= " </dlf:item>\n";
137 $out .= " </dlf:items>\n";
138 $out .= " </dlf:record>\n";
142 my $items = Koha
::Items
->search({ biblionumber
=> $id });
145 $out .= " <dlf:record>\n";
146 $out .= " <dlf:bibliographic id=\"" .$id. "\" />\n";
147 $out .= " <dlf:items>\n";
148 # We loop over the items to clean them
149 while ( my $item = $items->next ) {
150 my $itemnumber = $item->itemnumber;
151 my ( $biblionumber, $status, $msg, $location ) = _availability
($itemnumber);
152 $out .= " <dlf:item id=\"" . $itemnumber . "\">\n";
153 $out .= " <dlf:simpleavailability>\n";
154 $out .= " <dlf:identifier>" . $itemnumber . "</dlf:identifier>\n";
155 $out .= " <dlf:availabilitystatus>" . $status . "</dlf:availabilitystatus>\n";
156 if ($msg) { $out .= " <dlf:availabilitymsg>" . $msg . "</dlf:availabilitymsg>\n"; }
157 if ($location) { $out .= " <dlf:location>" . $location . "</dlf:location>\n"; }
158 $out .= " </dlf:simpleavailability>\n";
159 $out .= " </dlf:item>\n";
162 $out .= " </dlf:items>\n";
163 $out .= " </dlf:record>\n";
166 $msg = "Error: could not retrieve availability for this ID";
170 $out .= "</dlf:collection>\n";
177 Given a list of biblionumbers, returns a list of record objects that
178 contain bibliographic information, as well as associated holdings and item
179 information. The caller may request a specific metadata schema for the
180 record objects to be returned.
182 This function behaves similarly to HarvestBibliographicRecords and
183 HarvestExpandedRecords in Data Aggregation, but allows quick, real time
184 lookup by bibliographic identifier.
186 You can use OAI-PMH ListRecords instead of this service.
191 list of system record identifiers
193 Defines the metadata schema in which the records are returned,
202 # Check if the schema is supported. For now, GetRecords only supports MARCXML
203 if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
204 return { code
=> 'UnsupportedSchema' };
209 # Loop over biblionumbers
210 foreach my $biblionumber ( split( / /, $cgi->param('id') ) ) {
212 # Get the biblioitem from the biblionumber
213 my $biblio = Koha
::Biblios
->find( $biblionumber );
215 push @records, { code
=> "RecordNotFound" };
219 my $biblioitem = $biblio->biblioitem->unblessed;
222 my $record = GetMarcBiblio
({
223 biblionumber
=> $biblionumber,
224 embed_items
=> $embed_items });
226 $biblioitem->{marcxml
} = $record->as_xml_record();
229 # Get most of the needed data
230 my $biblioitemnumber = $biblioitem->{'biblioitemnumber'};
231 my $holds = $biblio->current_holds->unblessed;
232 my $issues = GetBiblioIssues
($biblionumber);
233 my @items = $biblio->items->as_list;
235 $biblioitem->{items
}->{item
} = [];
237 # We loop over the items to clean them
238 foreach my $item (@items) {
239 my %item = %{ $item->unblessed };
241 # This hides additionnal XML subfields, we don't need these info
242 delete $item{'more_subfields_xml'};
244 # Display branch names instead of branch codes
245 my $home_library = $item->home_branch;
246 my $holding_library = $item->holding_branch;
247 $item{'homebranchname'} = $home_library ?
$home_library->branchname : '';
248 $item{'holdingbranchname'} = $holding_library ?
$holding_library->branchname : '';
250 my $transfer = $item->get_transfer;
253 datesent
=> $transfer->datesent,
254 frombranch
=> $transfer->frombranch,
255 tobranch
=> $transfer->tobranch,
259 push @
{ $biblioitem->{items
}->{item
} }, \
%item;
262 # Hashref building...
263 $biblioitem->{'reserves'}->{'reserve'} = $holds;
264 $biblioitem->{'issues'}->{'issue'} = $issues;
266 push @records, $biblioitem;
269 return { record
=> \
@records };
272 =head2 GetAuthorityRecords
274 Given a list of authority record identifiers, returns a list of record
275 objects that contain the authority records. The function user may request
276 a specific metadata schema for the record objects.
281 list of authority record identifiers
283 specifies the metadata schema of records to be returned, possible values:
288 sub GetAuthorityRecords
{
291 # If the user asks for an unsupported schema, return an error code
292 if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
293 return { code
=> 'UnsupportedSchema' };
298 # Let's loop over the authority IDs
299 foreach my $authid ( split( / /, $cgi->param('id') ) ) {
301 # Get the record as XML string, or error code
302 push @records, GetAuthorityXML
($authid) || { code
=> 'RecordNotFound' };
305 return { record
=> \
@records };
310 Looks up a patron in the ILS by an identifier, and returns the borrowernumber.
315 an identifier used to look up the patron in Koha
317 the type of the identifier, possible values:
330 my $id = $cgi->param('id');
332 return { message
=> 'PatronNotFound' };
336 my $passed_id_type = $cgi->param('id_type');
337 if($passed_id_type) {
338 $patrons = Koha
::Patrons
->search( { $passed_id_type => $id } );
340 foreach my $id_type ('cardnumber', 'userid', 'email', 'borrowernumber',
341 'surname', 'firstname') {
342 $patrons = Koha
::Patrons
->search( { $id_type => $id } );
343 last if($patrons->count);
346 unless ( $patrons->count ) {
347 return { message
=> 'PatronNotFound' };
350 return { id
=> $patrons->next->borrowernumber };
353 =head2 AuthenticatePatron
355 Authenticates a user's login credentials and returns the identifier for
360 - username (Required)
361 user's login identifier (userid or cardnumber)
362 - password (Required)
367 sub AuthenticatePatron
{
369 my $username = $cgi->param('username');
370 my $password = $cgi->param('password');
371 my ($status, $cardnumber, $userid) = C4
::Auth
::checkpw
( C4
::Context
->dbh, $username, $password );
374 my $patron = Koha
::Patrons
->find( { userid
=> $userid } );
375 return { id
=> $patron->borrowernumber };
378 return { code
=> 'PatronNotFound' };
384 Returns specified information about the patron, based on options in the
385 request. This function can optionally return patron's contact information,
386 fine information, hold request information, and loan information.
390 - patron_id (Required)
392 - show_contact (Optional, default 1)
393 whether or not to return patron's contact information in the response
394 - show_fines (Optional, default 0)
395 whether or not to return fine information in the response
396 - show_holds (Optional, default 0)
397 whether or not to return hold request information in the response
398 - show_loans (Optional, default 0)
399 whether or not to return loan information request information in the response
400 - show_attributes (Optional, default 0)
401 whether or not to return additional patron attributes, when enabled the attributes
402 are limited to those marked as opac visible only.
410 my $borrowernumber = $cgi->param('patron_id');
411 my $patron = Koha
::Patrons
->find( $borrowernumber );
412 return { code
=> 'PatronNotFound' } unless $patron;
414 # Cleaning the borrower hashref
415 my $borrower = $patron->unblessed;
416 $borrower->{charges
} = sprintf "%.02f", $patron->account->non_issues_charges; # FIXME Formatting should not be done here
417 my $library = Koha
::Libraries
->find( $borrower->{branchcode
} );
418 $borrower->{'branchname'} = $library ?
$library->branchname : '';
419 delete $borrower->{'userid'};
420 delete $borrower->{'password'};
422 # Contact fields management
423 if ( defined $cgi->param('show_contact') && $cgi->param('show_contact') eq "0" ) {
425 # Define contact fields
426 my @contactfields = (
427 'email', 'emailpro', 'fax', 'mobile', 'phone', 'phonepro',
428 'streetnumber', 'zipcode', 'city', 'streettype', 'B_address', 'B_city',
429 'B_email', 'B_phone', 'B_zipcode', 'address', 'address2', 'altcontactaddress1',
430 'altcontactaddress2', 'altcontactaddress3', 'altcontactfirstname', 'altcontactphone', 'altcontactsurname', 'altcontactzipcode'
434 foreach my $field (@contactfields) {
435 delete $borrower->{$field};
440 if ( $cgi->param('show_fines') && $cgi->param('show_fines') eq "1" ) {
441 $borrower->{fines
}{fine
} = $patron->account->lines->unblessed;
444 # Reserves management
445 if ( $cgi->param('show_holds') && $cgi->param('show_holds') eq "1" ) {
447 # Get borrower's reserves
448 my $holds = $patron->holds;
449 while ( my $hold = $holds->next ) {
451 my ( $item, $biblio, $biblioitem ) = ( {}, {}, {} );
452 # Get additional informations
453 if ( $hold->itemnumber ) { # item level holds
454 $item = Koha
::Items
->find( $hold->itemnumber );
455 $biblio = $item->biblio;
456 $biblioitem = $biblio->biblioitem;
458 # Remove unwanted fields
459 $item = $item->unblessed;
460 delete $item->{more_subfields_xml
};
461 $biblio = $biblio->unblessed;
462 $biblioitem = $biblioitem->unblessed;
465 # Add additional fields
466 my $unblessed_hold = $hold->unblessed;
467 $unblessed_hold->{item
} = { %$item, %$biblio, %$biblioitem };
468 my $library = Koha
::Libraries
->find( $hold->branchcode );
469 my $branchname = $library ?
$library->branchname : '';
470 $unblessed_hold->{branchname
} = $branchname;
471 $biblio = Koha
::Biblios
->find( $hold->biblionumber ); # Should be $hold->get_biblio
472 $unblessed_hold->{title
} = $biblio ?
$biblio->title : ''; # Just in case, but should not be needed
474 push @
{ $borrower->{holds
}{hold
} }, $unblessed_hold;
480 if ( $cgi->param('show_loans') && $cgi->param('show_loans') eq "1" ) {
481 my $per_page = $cgi->param('loans_per_page');
482 my $page = $cgi->param('loans_page');
484 my $pending_checkouts = $patron->pending_checkouts;
486 if ($page || $per_page) {
489 $borrower->{total_loans
} = $pending_checkouts->count();
490 $pending_checkouts = $pending_checkouts->search(undef, {
497 while ( my $c = $pending_checkouts->next ) {
498 # FIXME We should only retrieve what is needed in the template
499 my $issue = $c->unblessed_all_relateds;
500 delete $issue->{'more_subfields_xml'};
501 push @checkouts, $issue
503 $borrower->{'loans'}->{'loan'} = \
@checkouts;
506 my $show_attributes = $cgi->param('show_attributes');
507 if ( $show_attributes && $show_attributes eq "1" ) {
508 my $attrs = GetBorrowerAttributes
( $borrowernumber, 1 );
509 $borrower->{'attributes'} = $attrs;
512 # Add is expired information
513 $borrower->{'is_expired'} = $patron->is_expired ?
1 : 0;
518 =head2 GetPatronStatus
520 Returns a patron's status information.
524 - patron_id (Required)
529 sub GetPatronStatus
{
533 my $borrowernumber = $cgi->param('patron_id');
534 my $patron = Koha
::Patrons
->find( $borrowernumber );
535 return { code
=> 'PatronNotFound' } unless $patron;
539 type
=> $patron->categorycode,
541 expiry
=> $patron->dateexpiry,
547 Returns information about the services available on a particular item for
552 - patron_id (Required)
562 # Get the member, or return an error code if not found
563 my $borrowernumber = $cgi->param('patron_id');
564 my $patron = Koha
::Patrons
->find( $borrowernumber );
565 return { code
=> 'PatronNotFound' } unless $patron;
567 my $borrower = $patron->unblessed;
568 # Get the item, or return an error code if not found
569 my $itemnumber = $cgi->param('item_id');
570 my $item = Koha
::Items
->find($itemnumber);
571 return { code
=> 'RecordNotFound' } unless $item;
575 # Reserve level management
576 my $biblionumber = $item->biblionumber;
577 my $canbookbereserved = CanBookBeReserved
( $borrower, $biblionumber );
578 if ($canbookbereserved->{status
} eq 'OK') {
579 push @availablefor, 'title level hold';
580 my $canitembereserved = IsAvailableForItemLevelRequest
($item, $patron);
581 if ($canitembereserved) {
582 push @availablefor, 'item level hold';
586 # Reserve cancellation management
587 my $holds = $patron->holds;
589 while ( my $hold = $holds->next ) { # FIXME This could be improved
590 push @reserveditems, $hold->itemnumber;
592 if ( grep { $itemnumber eq $_ } @reserveditems ) {
593 push @availablefor, 'hold cancellation';
597 my @renewal = CanBookBeRenewed
( $borrowernumber, $itemnumber );
599 push @availablefor, 'loan renewal';
603 my $barcode = $item->barcode || '';
604 $barcode = barcodedecode
($barcode) if ( $barcode && C4
::Context
->preference('itemBarcodeInputFilter') );
606 my ( $issuingimpossible, $needsconfirmation ) = CanBookBeIssued
( $patron, $barcode );
608 # TODO push @availablefor, 'loan';
612 $out->{'AvailableFor'} = \
@availablefor;
619 Extends the due date for a borrower's existing issue.
623 - patron_id (Required)
627 - desired_due_date (Required)
628 the date the patron would like the item returned by
635 # Get borrower infos or return an error code
636 my $borrowernumber = $cgi->param('patron_id');
637 my $patron = Koha
::Patrons
->find( $borrowernumber );
638 return { code
=> 'PatronNotFound' } unless $patron;
640 # Get the item, or return an error code
641 my $itemnumber = $cgi->param('item_id');
642 my $item = Koha
::Items
->find($itemnumber);
643 return { code
=> 'RecordNotFound' } unless $item;
645 # Add renewal if possible
646 my @renewal = CanBookBeRenewed
( $borrowernumber, $itemnumber );
647 if ( $renewal[0] ) { AddRenewal
( $borrowernumber, $itemnumber ); }
649 my $issue = $item->checkout;
650 return unless $issue; # FIXME should be handled
654 $out->{'renewals'} = $issue->renewals;
655 $out->{date_due
} = dt_from_string
($issue->date_due)->strftime('%Y-%m-%d %H:%M');
656 $out->{'success'} = $renewal[0];
657 $out->{'error'} = $renewal[1];
664 Creates, for a borrower, a biblio-level hold reserve.
668 - patron_id (Required)
672 - request_location (Required)
673 IP address where the end user request is being placed
674 - pickup_location (Optional)
675 a branch code indicating the location to which to deliver the item for pickup
676 - needed_before_date (Optional)
677 date after which hold request is no longer needed
678 - pickup_expiry_date (Optional)
679 date after which item returned to shelf if item is not picked up
686 # Get the borrower or return an error code
687 my $borrowernumber = $cgi->param('patron_id');
688 my $patron = Koha
::Patrons
->find( $borrowernumber );
689 return { code
=> 'PatronNotFound' } unless $patron;
691 # If borrower is restricted return an error code
692 return { code
=> 'PatronRestricted' } if $patron->is_debarred;
694 # Get the biblio record, or return an error code
695 my $biblionumber = $cgi->param('bib_id');
696 my $biblio = Koha
::Biblios
->find( $biblionumber );
697 return { code
=> 'RecordNotFound' } unless $biblio;
699 my @hostitems = get_hostitemnumbers_of
($biblionumber);
702 push(@itemnumbers, @hostitems);
705 my $items = Koha
::Items
->search({ -or => { biblionumber
=> $biblionumber, itemnumber
=> { in => \
@itemnumbers } } });
707 unless ( $items->count ) {
708 return { code
=> 'NoItems' };
711 my $title = $biblio ?
$biblio->title : '';
713 # Check if the biblio can be reserved
714 my $code = CanBookBeReserved
( $borrowernumber, $biblionumber )->{status
};
715 return { code
=> $code } unless ( $code eq 'OK' );
719 # Pickup branch management
720 if ( $cgi->param('pickup_location') ) {
721 $branch = $cgi->param('pickup_location');
722 return { code
=> 'LocationNotFound' } unless Koha
::Libraries
->find($branch);
723 } else { # if the request provide no branch, use the borrower's branch
724 $branch = $patron->branchcode;
727 my $destination = Koha
::Libraries
->find($branch);
728 return { code
=> 'libraryNotPickupLocation' } unless $destination->pickup_location;
729 return { code
=> 'cannotBeTransferred' } unless $biblio->can_be_transferred({ to
=> $destination });
732 # $branch, $borrowernumber, $biblionumber,
733 # $constraint, $bibitems, $priority, $resdate, $expdate, $notes,
734 # $title, $checkitem, $found
735 my $priority= C4
::Reserves
::CalculatePriority
( $biblionumber );
739 borrowernumber
=> $borrowernumber,
740 biblionumber
=> $biblionumber,
741 priority
=> $priority,
748 $out->{'title'} = $title;
749 my $library = Koha
::Libraries
->find( $branch );
750 $out->{'pickup_location'} = $library ?
$library->branchname : '';
752 # TODO $out->{'date_available'} = '';
759 Creates, for a borrower, an item-level hold request on a specific item of
760 a bibliographic record in Koha.
764 - patron_id (Required)
770 - pickup_location (Optional)
771 a branch code indicating the location to which to deliver the item for pickup
772 - needed_before_date (Optional)
773 date after which hold request is no longer needed
774 - pickup_expiry_date (Optional)
775 date after which item returned to shelf if item is not picked up
782 # Get the borrower or return an error code
783 my $borrowernumber = $cgi->param('patron_id');
784 my $patron = Koha
::Patrons
->find( $borrowernumber );
785 return { code
=> 'PatronNotFound' } unless $patron;
787 # If borrower is restricted return an error code
788 return { code
=> 'PatronRestricted' } if $patron->is_debarred;
790 # Get the biblio or return an error code
791 my $biblionumber = $cgi->param('bib_id');
792 my $biblio = Koha
::Biblios
->find( $biblionumber );
793 return { code
=> 'RecordNotFound' } unless $biblio;
795 my $title = $biblio ?
$biblio->title : '';
797 # Get the item or return an error code
798 my $itemnumber = $cgi->param('item_id');
799 my $item = Koha
::Items
->find($itemnumber);
800 return { code
=> 'RecordNotFound' } unless $item;
802 # If the biblio does not match the item, return an error code
803 return { code
=> 'RecordNotFound' } if $item->biblionumber ne $biblio->biblionumber;
805 # Pickup branch management
807 if ( $cgi->param('pickup_location') ) {
808 $branch = $cgi->param('pickup_location');
809 return { code
=> 'LocationNotFound' } unless Koha
::Libraries
->find($branch);
810 } else { # if the request provide no branch, use the borrower's branch
811 $branch = $patron->branchcode;
814 # Check for item disponibility
815 my $canitembereserved = C4
::Reserves
::CanItemBeReserved
( $borrowernumber, $itemnumber, $branch )->{status
};
816 return { code
=> $canitembereserved } unless $canitembereserved eq 'OK';
819 my $priority = C4
::Reserves
::CalculatePriority
($biblionumber);
823 borrowernumber
=> $borrowernumber,
824 biblionumber
=> $biblionumber,
825 priority
=> $priority,
827 itemnumber
=> $itemnumber,
833 my $library = Koha
::Libraries
->find( $branch );
834 $out->{'pickup_location'} = $library ?
$library->branchname : '';
836 # TODO $out->{'date_available'} = '';
843 Cancels an active reserve request for the borrower.
847 - patron_id (Required)
857 # Get the borrower or return an error code
858 my $borrowernumber = $cgi->param('patron_id');
859 my $patron = Koha
::Patrons
->find( $borrowernumber );
860 return { code
=> 'PatronNotFound' } unless $patron;
862 # Get the reserve or return an error code
863 my $reserve_id = $cgi->param('item_id');
864 my $hold = Koha
::Holds
->find( $reserve_id );
865 return { code
=> 'RecordNotFound' } unless $hold;
866 return { code
=> 'RecordNotFound' } unless ($hold->borrowernumber == $borrowernumber);
870 return { code
=> 'Canceled' };
875 Returns, for an itemnumber, an array containing availability information.
877 my ($biblionumber, $status, $msg, $location) = _availability($id);
882 my ($itemnumber) = @_;
883 my $item = Koha
::Items
->find($itemnumber);
886 return ( undef, 'unknown', 'Error: could not retrieve availability for this ID', undef );
889 my $biblionumber = $item->biblioitemnumber;
890 my $library = Koha
::Libraries
->find( $item->holdingbranch );
891 my $location = $library ?
$library->branchname : '';
893 if ( $item->notforloan ) {
894 return ( $biblionumber, 'not available', 'Not for loan', $location );
895 } elsif ( $item->onloan ) {
896 return ( $biblionumber, 'not available', 'Checked out', $location );
897 } elsif ( $item->itemlost ) {
898 return ( $biblionumber, 'not available', 'Item lost', $location );
899 } elsif ( $item->withdrawn ) {
900 return ( $biblionumber, 'not available', 'Item withdrawn', $location );
901 } elsif ( $item->damaged ) {
902 return ( $biblionumber, 'not available', 'Item damaged', $location );
904 return ( $biblionumber, 'available', undef, $location );