=head1 NAME ILS::Patron - Portable Patron status object class for SIP =head1 DESCRIPTION A C object holds information about a patron that's used by self service terminals to authenticate and authorize a patron, and to display information about the patron's borrowing activity. =head1 SYNOPSIS use ILS; use ILS::Patron; # Look up patron based on patron_id my $patron = new ILS::Patron $patron_id # Basic object access methods $patron_id = $patron->id; $str = $patron->name; $str = $patron->address; $str = $patron->email_addr; $str = $patron->home_phone; $str = $patron->sip_birthdate; $str = $patron->ptype; $str = $patron->language; $str = $patron->password; $str = $patron->check_password($password); $str = $patron->currency; $str = $patron->screen_msg; $str = $patron->print_line; # Check patron permissions $bool = $patron->charge_ok; $bool = $patron->renew_ok; $bool = $patron->recall_ok; $bool = $patron->hold_ok; $bool = $patron->card_lost; $bool = $patron->too_many_charged; $bool = $patron->too_many_overdue; $bool = $patron->too_many_renewal; $bool = $patron->too_many_claim_return; $bool = $patron->too_many_lost; $bool = $patron->excessive_fines; $bool = $patron->excessive_fees; $bool = $patron->too_many_billed; # Patron borrowing activity $num = $patron->recall_overdue; $num = $patron->fee_amount; $bool = $patron->drop_hold($item_id); @holds = $patron->hold_items($start, $end); @items = $patron->overdue_items($start, $end); @items = $patron->charged_items($start, $end); @items = $patron->fine_items($start, $end); @items = $patron->recall_items($start, $end); @items = $patron->unavail_holds($start, $end); # Changing a patron's status $patron->block($card_retained, $blocked_msg); $patron->enable; =head1 INITIALIZATION A patron object is created by calling $patron = new ILS::Patron $patron_id; where C<$patron_id> is the patron's barcode as received from the self service terminal. If the patron barcode is not registered, then C should return C. =head1 BASIC OBJECT ACCESS METHODS The following functions return the corresponding information about the given patron, or C if the information is unavailable. $patron_id = $patron-Eid; $str = $patron-Ename; $str = $patron-Eaddress; $str = $patron-Eemail_addr; $str = $patron-Ehome_phone; $str = $patron-Escreen_msg; $str = $patron-Eprint_line; If there are outstanding display messages associated with the patron, then these return the screen message and print line, respectively, as with the C methods. There are a few other object access methods that need a bit more explication however. =head2 C<$str = $patron-Esip_birthdate;> Returns the patron's birthday formated according to the SIP specification: YYYYMMDD HHMMSS =head2 C<$str = $patron-Eptype;> Returns the "patron type" of the patron. This is not used by the SIP server code, but is passed through to the self service terminal (using the non-standard protocol field "PC"). Some self service terminals use the patron type in determining what level of service to provide (for example, Envisionware computer management software can be configured to filter internet access based on patron type). =head2 C<$str = $patron-Elanguage;> A three-digit string encoding the patron's prefered language. The full list is defined in the SIP specification, but some of the important values are: 000 Unknown (default) 001 English 002 French 008 Spanish 011 Canadian French 016 Arabic 019 Chinese 021 North American Spanish =head2 C<$bool = $patron-Echeck_password($password);> Returns C if C<$patron>'s password is C<$password>. =head2 C<$str = $patron-Ecurrency;> Returns the three character ISO 4217 currency code for the patron's preferred currency. =head1 CHECKING PATRON PERMISSIONS Most of the methods associated with Patrons are related to checking if they're authorized to perform various actions: $bool = $patron-Echarge_ok; $bool = $patron-Erenew_ok; $bool = $patron-Erecall_ok; $bool = $patron-Ehold_ok; $bool = $patron-Ecard_lost; $bool = $patron-Erecall_overdue; $bool = $patron-Etoo_many_charged; $bool = $patron-Etoo_many_overdue; $bool = $patron-Etoo_many_renewal; $bool = $patron-Etoo_many_claim_return; $bool = $patron-Etoo_many_lost; $bool = $patron-Eexcessive_fines; $bool = $patron-Eexcessive_fees; $bool = $patron-Etoo_many_billed; =head1 LISTS OF ITEMS ASSOCIATED WITH THE USER The C<$patron> object provides a set of methods to find out information about various sets that are associated with the user. All these methods take two optional parameters: C<$start> and C<$end>, which define a subset of the list of items to be returned (C<1> is the first item in the list). The following methods all return a reference to a list of C<$item_id>s: $items = $patron-Ehold_items($start, $end); $items = $patron-Eoverdue_items($start, $end); $items = $patron-Echarged_items($start, $end); $items = $patron-Erecall_items($start, $end); $items = $patron-Eunavail_holds($start, $end); It is also possible to retrieve an itemized list of the fines outstanding. This method returns a reference to an itemized list of fines: $fines = $patron-Efine_items($start, $end); =head1 PATRON BORROWING ACTIVITY =head2 C<$num = $patron-Efee_amount;> The total amount of fees and fines owed by the patron. =head2 C<$bool = $patron-Edrop_hold($item_id);> Drops the hold that C<$patron> has placed on the item C<$item_id>. Returns C if the patron did not have a hold on the item, C otherwise. =head1 CHANGING A PATRON'S STATUS =head2 C<$status = $ils-Eblock($card_retained, $blocked_card_msg);> Block the account of the patron identified by C<$patron_id>. If the self check unit captured the patron's card, then C<$card_retained> will be C. A message indicating why the card was retained will be provided by the parameter C<$blocked_card_msg>. This function returns an C object that has been updated to indicate that the patron's privileges have been blocked, or C if the patron ID is not valid. =head2 C<$patron-Eenable;> Reenable the patron after she's been blocked. This is a test function and will not normally be called by self-service terminals in production.