File Coverage

=head1 NAME

C4::ILS-DI::Services - ILS-DI Services

=head1 DESCRIPTION

Each function in this module represents an ILS-DI service.
They all takes a CGI instance as argument and most of them return a 
hashref that will be printed by XML::Simple in opac/ilsdi.pl

=head1 SYNOPSIS

	use C4::ILSDI::Services;
	use XML::Simple;
	use CGI;

	my $cgi = new CGI;

	$out = LookupPatron($cgi);

	print CGI::header('text/xml');
	print XMLout($out,
		noattr => 1, 
		noescape => 1,
		nosort => 1,
		xmldecl => '<?xml version="1.0" encoding="ISO-8859-1" ?>', 
		RootName => 'LookupPatron', 
		SuppressEmpty => 1);

=cut

=head1 FUNCTIONS

=head2 GetAvailability

Given a set of biblionumbers or itemnumbers, returns a list with 
availability of the items associated with the identifiers.

Parameters:

=head3 id (Required)

list of either biblionumbers or itemnumbers

=head3 id_type (Required)

defines the type of record identifier being used in the request, 
possible values:

  - bib
  - item

=head3 return_type (Optional)

requests a particular level of detail in reporting availability, 
possible values:

  - bib
  - item

=head3 return_fmt (Optional)

requests a particular format or set of formats in reporting 
availability 

=cut

=head2 GetRecords

Given a list of biblionumbers, returns a list of record objects that 
contain bibliographic information, as well as associated holdings and item
information. The caller may request a specific metadata schema for the 
record objects to be returned.

This function behaves similarly to HarvestBibliographicRecords and 
HarvestExpandedRecords in Data Aggregation, but allows quick, real time 
lookup by bibliographic identifier.

You can use OAI-PMH ListRecords instead of this service.

Parameters:

  - id (Required)
	list of system record identifiers
  - id_type (Optional)
	Defines the metadata schema in which the records are returned, 
	possible values:
  	  - MARCXML

=cut

=head2 GetAuthorityRecords

Given a list of authority record identifiers, returns a list of record 
objects that contain the authority records. The function user may request 
a specific metadata schema for the record objects.

Parameters:

  - id (Required)
    list of authority record identifiers
  - schema (Optional)
    specifies the metadata schema of records to be returned, possible values:
      - MARCXML

=cut

=head2 LookupPatron

Looks up a patron in the ILS by an identifier, and returns the borrowernumber.

Parameters:

  - id (Required)
	an identifier used to look up the patron in Koha
  - id_type (Optional)
	the type of the identifier, possible values:
	- cardnumber
	- firstname
	- userid
	- borrowernumber

=cut

=head2 AuthenticatePatron

Authenticates a user's login credentials and returns the identifier for 
the patron.

Parameters:

  - username (Required)
	user's login identifier
  - password (Required)
	user's password

=cut

=head2 GetPatronInfo

Returns specified information about the patron, based on options in the 
request. This function can optionally return patron's contact information, 
fine information, hold request information, and loan information.

Parameters:

  - patron_id (Required)
	the borrowernumber
  - show_contact (Optional, default 1)
	whether or not to return patron's contact information in the response
  - show_fines (Optional, default 0)
	whether or not to return fine information in the response
  - show_holds (Optional, default 0)
	whether or not to return hold request information in the response
  - show_loans (Optional, default 0)
	whether or not to return loan information request information in the response 

=cut

=head2 GetPatronStatus

Returns a patron's status information.

Parameters:

  - patron_id (Required)
	the borrower ID

=cut

=head2 GetServices

Returns information about the services available on a particular item for 
a particular patron.

Parameters:

  - patron_id (Required)
	a borrowernumber
  - item_id (Required)
	an itemnumber
=cut

=head2 RenewLoan

Extends the due date for a borrower's existing issue.

Parameters:

  - patron_id (Required)
	a borrowernumber
  - item_id (Required)
	an itemnumber
  - desired_due_date (Required)
	the date the patron would like the item returned by 

=cut

=head2 HoldTitle

Creates, for a borrower, a biblio-level hold reserve.

Parameters:

  - patron_id (Required)
	a borrowernumber
  - bib_id (Required)
	a biblionumber
  - request_location (Required)
	IP address where the end user request is being placed
  - pickup_location (Optional)
	a branch code indicating the location to which to deliver the item for pickup
  - needed_before_date (Optional)
	date after which hold request is no longer needed
  - pickup_expiry_date (Optional)
	date after which item returned to shelf if item is not picked up 

=cut

=head2 HoldItem

Creates, for a borrower, an item-level hold request on a specific item of 
a bibliographic record in Koha.

Parameters:

  - patron_id (Required)
	a borrowernumber
  - bib_id (Required)
	a biblionumber
  - item_id (Required)
	an itemnumber
  - pickup_location (Optional)
	a branch code indicating the location to which to deliver the item for pickup
  - needed_before_date (Optional)
	date after which hold request is no longer needed
  - pickup_expiry_date (Optional)
	date after which item returned to shelf if item is not picked up 

=cut

=head2 CancelHold

Cancels an active reserve request for the borrower.

Parameters:

  - patron_id (Required)
	a borrowernumber
  - item_id (Required)
	an itemnumber 

=cut