C4/SIP/ILS/Patron.pod

   1 =head1 NAME
   2
   3 ILS::Patron - Portable Patron status object class for SIP
   4
   5 =head1 DESCRIPTION
   6
   7 A C<ILS::Patron> object holds information about a patron that's
   8 used by self service terminals to authenticate and authorize a patron,
   9 and to display information about the patron's borrowing activity.
  10
  11 =head1 SYNOPSIS
  12
  13         use ILS;
  14         use ILS::Patron;
  15
  16         # Look up patron based on patron_id
  17         my $patron = new ILS::Patron $patron_id
  18
  19         # Basic object access methods
  20         $patron_id = $patron->id;
  21         $str = $patron->name;
  22         $str = $patron->address;
  23         $str = $patron->email_addr;
  24         $str = $patron->home_phone;
  25         $str = $patron->sip_birthdate;
  26         $str = $patron->ptype;
  27         $str = $patron->language;
  28         $str = $patron->password;
  29         $str = $patron->check_password($password);
  30         $str = $patron->currency;
  31         $str = $patron->screen_msg;
  32         $str = $patron->print_line;
  33
  34         # Check patron permissions
  35         $bool = $patron->charge_ok;
  36         $bool = $patron->renew_ok;
  37         $bool = $patron->recall_ok;
  38         $bool = $patron->hold_ok;
  39         $bool = $patron->card_lost;
  40         $bool = $patron->too_many_charged;
  41         $bool = $patron->too_many_overdue;
  42         $bool = $patron->too_many_renewal;
  43         $bool = $patron->too_many_claim_return;
  44         $bool = $patron->too_many_lost;
  45         $bool = $patron->excessive_fines;
  46         $bool = $patron->excessive_fees;
  47         $bool = $patron->too_many_billed;
  48
  49         # Patron borrowing activity
  50         $num = $patron->recall_overdue;
  51         $num = $patron->fee_amount;
  52         $bool = $patron->drop_hold($item_id);
  53         @holds = $patron->hold_items($start, $end);
  54         @items = $patron->overdue_items($start, $end);
  55         @items = $patron->charged_items($start, $end);
  56         @items = $patron->fine_items($start, $end);
  57         @items = $patron->recall_items($start, $end);
  58         @items = $patron->unavail_holds($start, $end);
  59
  60         # Changing a patron's status
  61         $patron->block($card_retained, $blocked_msg);
  62         $patron->enable;
  63
  64 =head1 INITIALIZATION
  65
  66 A patron object is created by calling
  67
  68         $patron = new ILS::Patron $patron_id;
  69
  70 where C<$patron_id> is the patron's barcode as received from the
  71 self service terminal.  If the patron barcode is not registered,
  72 then C<new> should return C<undef>.
  73
  74 =head1 BASIC OBJECT ACCESS METHODS
  75
  76 The following functions return the corresponding information
  77 about the given patron, or C<undef> if the information is
  78 unavailable.
  79
  80         $patron_id = $patron-E<gt>id;
  81         $str = $patron-E<gt>name;
  82         $str = $patron-E<gt>address;
  83         $str = $patron-E<gt>email_addr;
  84         $str = $patron-E<gt>home_phone;
  85
  86         $str = $patron-E<gt>screen_msg;
  87         $str = $patron-E<gt>print_line;
  88
  89 If there are outstanding display messages associated with the
  90 patron, then these return the screen message and print line,
  91 respectively, as with the C<ILS> methods.
  92
  93 There are a few other object access methods that need a bit more
  94 explication however.
  95
  96 =head2 C<$str = $patron-E<gt>sip_birthdate;>
  97
  98 Returns the patron's birthday formated according to the SIP
  99 specification:
 100
 101         YYYYMMDD    HHMMSS
 102
 103 =head2 C<$str = $patron-E<gt>ptype;>
 104
 105 Returns the "patron type" of the patron.  This is not used by the
 106 SIP server code, but is passed through to the self service
 107 terminal (using the non-standard protocol field "PC").  Some self
 108 service terminals use the patron type in determining what level
 109 of service to provide (for example, Envisionware computer
 110 management software can be configured to filter internet access
 111 based on patron type).
 112
 113 =head2 C<$str = $patron-E<gt>language;>
 114
 115 A three-digit string encoding the patron's prefered language.
 116 The full list is defined in the SIP specification, but some of
 117 the important values are:
 118
 119         000 Unknown (default)
 120         001 English
 121         002 French
 122         008 Spanish
 123         011 Canadian French
 124         016 Arabic
 125         019 Chinese
 126         021 North American Spanish
 127
 128 =head2 C<$bool = $patron-E<gt>check_password($password);>
 129
 130 Returns C<true> if C<$patron>'s password is C<$password>.
 131
 132 =head2 C<$str = $patron-E<gt>currency;>
 133
 134 Returns the three character ISO 4217 currency code for the
 135 patron's preferred currency.
 136
 137 =head1 CHECKING PATRON PERMISSIONS
 138
 139 Most of the methods associated with Patrons are related to
 140 checking if they're authorized to perform various actions:
 141
 142         $bool = $patron-E<gt>charge_ok;
 143         $bool = $patron-E<gt>renew_ok;
 144         $bool = $patron-E<gt>recall_ok;
 145         $bool = $patron-E<gt>hold_ok;
 146         $bool = $patron-E<gt>card_lost;
 147         $bool = $patron-E<gt>recall_overdue;
 148         $bool = $patron-E<gt>too_many_charged;
 149         $bool = $patron-E<gt>too_many_overdue;
 150         $bool = $patron-E<gt>too_many_renewal;
 151         $bool = $patron-E<gt>too_many_claim_return;
 152         $bool = $patron-E<gt>too_many_lost;
 153         $bool = $patron-E<gt>excessive_fines;
 154         $bool = $patron-E<gt>excessive_fees;
 155         $bool = $patron-E<gt>too_many_billed;
 156
 157 =head1 LISTS OF ITEMS ASSOCIATED WITH THE USER
 158
 159 The C<$patron> object provides a set of methods to find out
 160 information about various sets that are associated with the
 161 user.  All these methods take two optional parameters: C<$start>
 162 and C<$end>, which define a subset of the list of items to be
 163 returned (C<1> is the first item in the list).  The following
 164 methods all return a reference to a list of C<$item_id>s:
 165
 166         $items = $patron-E<gt>hold_items($start, $end);
 167         $items = $patron-E<gt>overdue_items($start, $end);
 168         $items = $patron-E<gt>charged_items($start, $end);
 169         $items = $patron-E<gt>recall_items($start, $end);
 170         $items = $patron-E<gt>unavail_holds($start, $end);
 171
 172 It is also possible to retrieve an itemized list of the fines
 173 outstanding.  This method returns a reference to an itemized list
 174 of fines:
 175
 176         $fines = $patron-E<gt>fine_items($start, $end);
 177
 178 =head1 PATRON BORROWING ACTIVITY
 179
 180 =head2 C<$num = $patron-E<gt>fee_amount;>
 181
 182 The total amount of fees and fines owed by the patron.
 183
 184 =head2 C<$bool = $patron-E<gt>drop_hold($item_id);>
 185
 186 Drops the hold that C<$patron> has placed on the item
 187 C<$item_id>.  Returns C<false> if the patron did not have a hold
 188 on the item, C<true> otherwise.
 189
 190
 191
 192 =head1 CHANGING A PATRON'S STATUS
 193
 194 =head2 C<$status = $ils-E<gt>block($card_retained, $blocked_card_msg);>
 195
 196 Block the account of the patron identified by C<$patron_id>.  If
 197 the self check unit captured the patron's card, then
 198 C<$card_retained> will be C<true>.  A message indicating why the
 199 card was retained will be provided by the parameter
 200 C<$blocked_card_msg>.
 201
 202 This function returns an C<ILS::Patron> object that has been
 203 updated to indicate that the patron's privileges have been
 204 blocked, or C<undef> if the patron ID is not valid.
 205
 206 =head2 C<$patron-E<gt>enable;>
 207
 208 Reenable the patron after she's been blocked.  This is a test
 209 function and will not normally be called by self-service
 210 terminals in production.