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
({
218 biblionumber
=> $biblionumber,
219 embed_items
=> $embed_items });
221 $biblioitem->{marcxml
} = $record->as_xml_record();
224 # Get most of the needed data
225 my $biblioitemnumber = $biblioitem->{'biblioitemnumber'};
226 my $biblio = Koha
::Biblios
->find( $biblionumber );
227 my $holds = $biblio->current_holds->unblessed;
228 my $issues = GetBiblioIssues
($biblionumber);
229 my $items = GetItemsByBiblioitemnumber
($biblioitemnumber);
231 # We loop over the items to clean them
232 foreach my $item (@
$items) {
234 # This hides additionnal XML subfields, we don't need these info
235 delete $item->{'more_subfields_xml'};
237 # Display branch names instead of branch codes
238 my $home_library = Koha
::Libraries
->find( $item->{homebranch
} );
239 my $holding_library = Koha
::Libraries
->find( $item->{holdingbranch
} );
240 $item->{'homebranchname'} = $home_library ?
$home_library->branchname : '';
241 $item->{'holdingbranchname'} = $holding_library ?
$holding_library->branchname : '';
244 # Hashref building...
245 $biblioitem->{'items'}->{'item'} = $items;
246 $biblioitem->{'reserves'}->{'reserve'} = $holds;
247 $biblioitem->{'issues'}->{'issue'} = $issues;
249 push @records, $biblioitem;
252 return { record
=> \
@records };
255 =head2 GetAuthorityRecords
257 Given a list of authority record identifiers, returns a list of record
258 objects that contain the authority records. The function user may request
259 a specific metadata schema for the record objects.
264 list of authority record identifiers
266 specifies the metadata schema of records to be returned, possible values:
271 sub GetAuthorityRecords
{
274 # If the user asks for an unsupported schema, return an error code
275 if ( $cgi->param('schema') and $cgi->param('schema') ne "MARCXML" ) {
276 return { code
=> 'UnsupportedSchema' };
281 # Let's loop over the authority IDs
282 foreach my $authid ( split( / /, $cgi->param('id') ) ) {
284 # Get the record as XML string, or error code
285 push @records, GetAuthorityXML
($authid) || { code
=> 'RecordNotFound' };
288 return { record
=> \
@records };
293 Looks up a patron in the ILS by an identifier, and returns the borrowernumber.
298 an identifier used to look up the patron in Koha
300 the type of the identifier, possible values:
311 my $patrons = Koha
::Patrons
->search( { $cgi->param('id_type') => $cgi->param('id') } );
312 unless ( $patrons->count ) {
313 return { message
=> 'PatronNotFound' };
316 return { id
=> $patrons->next->borrowernumber };
319 =head2 AuthenticatePatron
321 Authenticates a user's login credentials and returns the identifier for
326 - username (Required)
327 user's login identifier (userid or cardnumber)
328 - password (Required)
333 sub AuthenticatePatron
{
335 my $username = $cgi->param('username');
336 my $password = $cgi->param('password');
337 my ($status, $cardnumber, $userid) = C4
::Auth
::checkpw
( C4
::Context
->dbh, $username, $password );
340 my $patron = Koha
::Patrons
->find( { cardnumber
=> $cardnumber } );
341 return { id
=> $patron->borrowernumber };
344 return { code
=> 'PatronNotFound' };
350 Returns specified information about the patron, based on options in the
351 request. This function can optionally return patron's contact information,
352 fine information, hold request information, and loan information.
356 - patron_id (Required)
358 - show_contact (Optional, default 1)
359 whether or not to return patron's contact information in the response
360 - show_fines (Optional, default 0)
361 whether or not to return fine information in the response
362 - show_holds (Optional, default 0)
363 whether or not to return hold request information in the response
364 - show_loans (Optional, default 0)
365 whether or not to return loan information request information in the response
373 my $borrowernumber = $cgi->param('patron_id');
374 my $patron = Koha
::Patrons
->find( $borrowernumber );
375 return { code
=> 'PatronNotFound' } unless $patron;
377 # Cleaning the borrower hashref
378 my $borrower = $patron->unblessed;
379 my $flags = C4
::Members
::patronflags
( $borrower );
380 $borrower->{'charges'} = $flags->{'CHARGES'}->{'amount'};
381 my $library = Koha
::Libraries
->find( $borrower->{branchcode
} );
382 $borrower->{'branchname'} = $library ?
$library->branchname : '';
383 delete $borrower->{'userid'};
384 delete $borrower->{'password'};
386 # Contact fields management
387 if ( defined $cgi->param('show_contact') && $cgi->param('show_contact') eq "0" ) {
389 # Define contact fields
390 my @contactfields = (
391 'email', 'emailpro', 'fax', 'mobile', 'phone', 'phonepro',
392 'streetnumber', 'zipcode', 'city', 'streettype', 'B_address', 'B_city',
393 'B_email', 'B_phone', 'B_zipcode', 'address', 'address2', 'altcontactaddress1',
394 'altcontactaddress2', 'altcontactaddress3', 'altcontactfirstname', 'altcontactphone', 'altcontactsurname', 'altcontactzipcode'
398 foreach my $field (@contactfields) {
399 delete $borrower->{$field};
404 if ( $cgi->param('show_fines') && $cgi->param('show_fines') eq "1" ) {
406 for ( my $i = 1 ; my @charge = getcharges
( $borrowernumber, undef, $i ) ; $i++ ) {
407 push( @charges, @charge );
409 $borrower->{'fines'}->{'fine'} = \
@charges;
412 # Reserves management
413 if ( $cgi->param('show_holds') && $cgi->param('show_holds') eq "1" ) {
415 # Get borrower's reserves
416 my $holds = $patron->holds;
417 while ( my $hold = $holds->next ) {
419 my ( $item, $biblio, $biblioitem ) = ( {}, {}, {} );
420 # Get additional informations
421 if ( $hold->itemnumber ) { # item level holds
422 $item = Koha
::Items
->find( $hold->itemnumber );
423 $biblio = $item->biblio;
424 $biblioitem = $biblio->biblioitem;
426 # Remove unwanted fields
427 $item = $item->unblessed;
428 delete $item->{more_subfields_xml
};
429 $biblio = $biblio->unblessed;
430 $biblioitem = $biblioitem->unblessed;
433 # Add additional fields
434 my $unblessed_hold = $hold->unblessed;
435 $unblessed_hold->{item
} = { %$item, %$biblio, %$biblioitem };
436 my $library = Koha
::Libraries
->find( $hold->branchcode );
437 my $branchname = $library ?
$library->branchname : '';
438 $unblessed_hold->{branchname
} = $branchname;
439 $biblio = Koha
::Biblios
->find( $hold->biblionumber ); # Should be $hold->get_biblio
440 $unblessed_hold->{title
} = $biblio ?
$biblio->title : ''; # Just in case, but should not be needed
442 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 $patron = Koha
::Patrons
->find( $borrowernumber );
482 return { code
=> 'PatronNotFound' } unless $patron;
486 type
=> $patron->categorycode,
488 expiry
=> $patron->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 $patron = Koha
::Patrons
->find( $borrowernumber );
512 return { code
=> 'PatronNotFound' } unless $patron;
514 my $borrower = $patron->unblessed;
515 # Get the item, or return an error code if not found
516 my $itemnumber = $cgi->param('item_id');
517 my $item = GetItem
( $itemnumber );
518 return { code
=> 'RecordNotFound' } unless $$item{itemnumber
};
522 # Reserve level management
523 my $biblionumber = $item->{'biblionumber'};
524 my $canbookbereserved = CanBookBeReserved
( $borrower, $biblionumber );
525 if ($canbookbereserved eq 'OK') {
526 push @availablefor, 'title level hold';
527 my $canitembereserved = IsAvailableForItemLevelRequest
($item, $borrower);
528 if ($canitembereserved) {
529 push @availablefor, 'item level hold';
533 # Reserve cancellation management
534 my $holds = $patron->holds;
536 while ( my $hold = $holds->next ) { # FIXME This could be improved
537 push @reserveditems, $hold->itemnumber;
539 if ( grep { $itemnumber eq $_ } @reserveditems ) {
540 push @availablefor, 'hold cancellation';
544 my @renewal = CanBookBeRenewed
( $borrowernumber, $itemnumber );
546 push @availablefor, 'loan renewal';
550 my $barcode = $item->{'barcode'} || '';
551 $barcode = barcodedecode
($barcode) if ( $barcode && C4
::Context
->preference('itemBarcodeInputFilter') );
553 my ( $issuingimpossible, $needsconfirmation ) = CanBookBeIssued
( $borrower, $barcode );
555 # TODO push @availablefor, 'loan';
559 $out->{'AvailableFor'} = \
@availablefor;
566 Extends the due date for a borrower's existing issue.
570 - patron_id (Required)
574 - desired_due_date (Required)
575 the date the patron would like the item returned by
582 # Get borrower infos or return an error code
583 my $borrowernumber = $cgi->param('patron_id');
584 my $patron = Koha
::Patrons
->find( $borrowernumber );
585 return { code
=> 'PatronNotFound' } unless $patron;
587 # Get the item, or return an error code
588 my $itemnumber = $cgi->param('item_id');
589 my $item = GetItem
( $itemnumber );
590 return { code
=> 'RecordNotFound' } unless $$item{itemnumber
};
592 # Add renewal if possible
593 my @renewal = CanBookBeRenewed
( $borrowernumber, $itemnumber );
594 if ( $renewal[0] ) { AddRenewal
( $borrowernumber, $itemnumber ); }
596 my $issue = Koha
::Checkouts
->find( { itemnumber
=> $itemnumber } ) or return; # FIXME should be handled
600 $out->{'renewals'} = $issue->renewals;
601 $out->{date_due
} = dt_from_string
($issue->date_due)->strftime('%Y-%m-%d %H:%S');
602 $out->{'success'} = $renewal[0];
603 $out->{'error'} = $renewal[1];
610 Creates, for a borrower, a biblio-level hold reserve.
614 - patron_id (Required)
618 - request_location (Required)
619 IP address where the end user request is being placed
620 - pickup_location (Optional)
621 a branch code indicating the location to which to deliver the item for pickup
622 - needed_before_date (Optional)
623 date after which hold request is no longer needed
624 - pickup_expiry_date (Optional)
625 date after which item returned to shelf if item is not picked up
632 # Get the borrower or return an error code
633 my $borrowernumber = $cgi->param('patron_id');
634 my $patron = Koha
::Patrons
->find( $borrowernumber );
635 return { code
=> 'PatronNotFound' } unless $patron;
637 # Get the biblio record, or return an error code
638 my $biblionumber = $cgi->param('bib_id');
639 my $biblio = Koha
::Biblios
->find( $biblionumber );
640 return { code
=> 'RecordNotFound' } unless $biblio;
642 my $title = $biblio ?
$biblio->title : '';
644 # Check if the biblio can be reserved
645 return { code
=> 'NotHoldable' } unless CanBookBeReserved
( $borrowernumber, $biblionumber ) eq 'OK';
649 # Pickup branch management
650 if ( $cgi->param('pickup_location') ) {
651 $branch = $cgi->param('pickup_location');
652 return { code
=> 'LocationNotFound' } unless Koha
::Libraries
->find($branch);
653 } else { # if the request provide no branch, use the borrower's branch
654 $branch = $patron->branchcode;
658 # $branch, $borrowernumber, $biblionumber,
659 # $constraint, $bibitems, $priority, $resdate, $expdate, $notes,
660 # $title, $checkitem, $found
661 my $priority= C4
::Reserves
::CalculatePriority
( $biblionumber );
662 AddReserve
( $branch, $borrowernumber, $biblionumber, undef, $priority, undef, undef, undef, $title, undef, undef );
666 $out->{'title'} = $title;
667 my $library = Koha
::Libraries
->find( $branch );
668 $out->{'pickup_location'} = $library ?
$library->branchname : '';
670 # TODO $out->{'date_available'} = '';
677 Creates, for a borrower, an item-level hold request on a specific item of
678 a bibliographic record in Koha.
682 - patron_id (Required)
688 - pickup_location (Optional)
689 a branch code indicating the location to which to deliver the item for pickup
690 - needed_before_date (Optional)
691 date after which hold request is no longer needed
692 - pickup_expiry_date (Optional)
693 date after which item returned to shelf if item is not picked up
700 # Get the borrower or return an error code
701 my $borrowernumber = $cgi->param('patron_id');
702 my $patron = Koha
::Patrons
->find( $borrowernumber );
703 return { code
=> 'PatronNotFound' } unless $patron;
705 # Get the biblio or return an error code
706 my $biblionumber = $cgi->param('bib_id');
707 my $biblio = Koha
::Biblios
->find( $biblionumber );
708 return { code
=> 'RecordNotFound' } unless $biblio;
710 my $title = $biblio ?
$biblio->title : '';
712 # Get the item or return an error code
713 my $itemnumber = $cgi->param('item_id');
714 my $item = GetItem
( $itemnumber );
715 return { code
=> 'RecordNotFound' } unless $$item{itemnumber
};
717 # If the biblio does not match the item, return an error code
718 return { code
=> 'RecordNotFound' } if $$item{biblionumber
} ne $biblio->biblionumber;
720 # Check for item disponibility
721 my $canitembereserved = C4
::Reserves
::CanItemBeReserved
( $borrowernumber, $itemnumber );
722 my $canbookbereserved = C4
::Reserves
::CanBookBeReserved
( $borrowernumber, $biblionumber );
723 return { code
=> 'NotHoldable' } unless $canbookbereserved eq 'OK' and $canitembereserved eq 'OK';
725 # Pickup branch management
727 if ( $cgi->param('pickup_location') ) {
728 $branch = $cgi->param('pickup_location');
729 return { code
=> 'LocationNotFound' } unless Koha
::Libraries
->find($branch);
730 } else { # if the request provide no branch, use the borrower's branch
731 $branch = $patron->branchcode;
735 # $branch, $borrowernumber, $biblionumber,
736 # $constraint, $bibitems, $priority, $resdate, $expdate, $notes,
737 # $title, $checkitem, $found
738 my $priority= C4
::Reserves
::CalculatePriority
( $biblionumber );
739 AddReserve
( $branch, $borrowernumber, $biblionumber, undef, $priority, undef, undef, undef, $title, $itemnumber, undef );
743 my $library = Koha
::Libraries
->find( $branch );
744 $out->{'pickup_location'} = $library ?
$library->branchname : '';
746 # TODO $out->{'date_available'} = '';
753 Cancels an active reserve request for the borrower.
757 - patron_id (Required)
767 # Get the borrower or return an error code
768 my $borrowernumber = $cgi->param('patron_id');
769 my $patron = Koha
::Patrons
->find( $borrowernumber );
770 return { code
=> 'PatronNotFound' } unless $patron;
772 # Get the reserve or return an error code
773 my $reserve_id = $cgi->param('item_id');
774 my $hold = Koha
::Holds
->find( $reserve_id );
775 return { code
=> 'RecordNotFound' } unless $hold;
776 return { code
=> 'RecordNotFound' } unless ($hold->borrowernumber == $borrowernumber);
780 return { code
=> 'Canceled' };
785 Returns, for an itemnumber, an array containing availability information.
787 my ($biblionumber, $status, $msg, $location) = _availability($id);
792 my ($itemnumber) = @_;
793 my $item = GetItem
( $itemnumber, undef, undef );
795 if ( not $item->{'itemnumber'} ) {
796 return ( undef, 'unknown', 'Error: could not retrieve availability for this ID', undef );
799 my $biblionumber = $item->{'biblioitemnumber'};
800 my $library = Koha
::Libraries
->find( $item->{holdingbranch
} );
801 my $location = $library ?
$library->branchname : '';
803 if ( $item->{'notforloan'} ) {
804 return ( $biblionumber, 'not available', 'Not for loan', $location );
805 } elsif ( $item->{'onloan'} ) {
806 return ( $biblionumber, 'not available', 'Checked out', $location );
807 } elsif ( $item->{'itemlost'} ) {
808 return ( $biblionumber, 'not available', 'Item lost', $location );
809 } elsif ( $item->{'withdrawn'} ) {
810 return ( $biblionumber, 'not available', 'Item withdrawn', $location );
811 } elsif ( $item->{'damaged'} ) {
812 return ( $biblionumber, 'not available', 'Item damaged', $location );
814 return ( $biblionumber, 'available', undef, $location );