3 ILS::Patron - Portable Patron status object class for SIP
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.
16 # Look up patron based on patron_id
17 my $patron = new ILS::Patron $patron_id
19 # Basic object access methods
20 $patron_id = $patron->id;
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;
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;
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);
60 # Changing a patron's status
61 $patron->block($card_retained, $blocked_msg);
66 A patron object is created by calling
68 $patron = new ILS::Patron $patron_id;
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>.
74 =head1 BASIC OBJECT ACCESS METHODS
76 The following functions return the corresponding information
77 about the given patron, or C<undef> if the information is
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;
86 $str = $patron-E<gt>screen_msg;
87 $str = $patron-E<gt>print_line;
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.
93 There are a few other object access methods that need a bit more
96 =head2 C<$str = $patron-E<gt>sip_birthdate;>
98 Returns the patron's birthday formatted according to the SIP
103 =head2 C<$str = $patron-E<gt>ptype;>
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).
113 =head2 C<$str = $patron-E<gt>language;>
115 A three-digit string encoding the patron's preferred language.
116 The full list is defined in the SIP specification, but some of
117 the important values are:
119 000 Unknown (default)
126 021 North American Spanish
128 =head2 C<$bool = $patron-E<gt>check_password($password);>
130 Returns C<true> if C<$patron>'s password is C<$password>.
132 =head2 C<$str = $patron-E<gt>currency;>
134 Returns the three character ISO 4217 currency code for the
135 patron's preferred currency.
137 =head1 CHECKING PATRON PERMISSIONS
139 Most of the methods associated with Patrons are related to
140 checking if they're authorized to perform various actions:
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;
157 =head1 LISTS OF ITEMS ASSOCIATED WITH THE USER
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:
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);
172 It is also possible to retrieve an itemized list of the fines
173 outstanding. This method returns a reference to an itemized list
176 $fines = $patron-E<gt>fine_items($start, $end);
178 =head1 PATRON BORROWING ACTIVITY
180 =head2 C<$num = $patron-E<gt>fee_amount;>
182 The total amount of fees and fines owed by the patron.
184 =head2 C<$bool = $patron-E<gt>drop_hold($item_id);>
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.
192 =head1 CHANGING A PATRON'S STATUS
194 =head2 C<$status = $ils-E<gt>block($card_retained, $blocked_card_msg);>
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>.
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.
206 =head2 C<$patron-E<gt>enable;>
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.