1 # Copyright (C) 2006-2008 Georgia Public Library Service
3 # Author: David J. Fiander
5 # This program is free software; you can redistribute it and/or modify
6 # it under the terms of the GNU General Public License as published by
7 # the Free Software Foundation; either version 2 of the License, or
8 # (at your option) any later version.
10 # This program is distributed in the hope that it will be useful,
11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 # GNU General Public License for more details.
15 # You should have received a copy of the GNU General Public License
16 # along with this program. If not, see <http://www.gnu.org/licenses/>.
20 ILS - Portability layer to interface between Open-SIP and ILS
26 # Initialize connection between SIP and the ILS
27 my $ils = new ILS (institution => 'Foo Public Library');
29 # Basic object access methods
30 $inst_name = $self->institution;
31 $bool = $self->support($operation);
32 $self->check_inst_id($inst_name, "error message");
34 # Check to see if certain protocol options are permitted
35 $bool = $self->checkout_ok;
36 $bool = $self->checkin_ok;
37 $bool = $self->status_update_ok;
38 $bool = $self->offline_ok;
40 $status = $ils->checkout($patron_id, $item_id, $sc_renew);
42 $status = $ils->checkin($item_id, $trans_date, $return_date,
43 $current_loc, $item_props, $cancel);
45 $status = $ils->end_patron_session($patron_id);
47 $status = $ils->pay_fee($patron_id, $patron_pwd, $fee_amt,
48 $fee_type, $pay_type, $fee_id, $trans_id,
51 $status = $ils->add_hold($patron_id, $patron_pwd, $item_id,
52 $title_id, $expiry_date,
53 $pickup_locn, $hold_type, $fee_ack);
55 $status = $ils->cancel_hold($patron_id, $patron_pwd,
58 $status = $ils->alter_hold($patron_id, $patron_pwd, $item_id,
59 $title_id, $expiry_date,
60 $pickup_locn, $hold_type,
63 $status = $ils->renew($patron_id, $patron_pwd, $item_id,
64 $title_id, $no_block, $nb_due_date,
65 $third_party, $item_props, $fee_ack);
67 $status = $ils->renew_all($patron_id, $patron_pwd, $fee_ack);
71 The ILS module defines a basic portability layer between the SIP
72 server and the rest of the integrated library system. It is the
73 responsibility of the ILS vendor to implement the functions
74 defined by this interface. This allows the SIP server to be
75 reasonably portable between ILS systems (of course, we won't know
76 exactly I<how> portable the interface is until it's been used by
79 Because no business logic is embedded in the SIP server code
80 itself, the SIP protocol handler functions do almost nothing
81 except decode the network messages and pass the parameters to the
82 ILS module or one of its submodules, C<ILS::Patron> and
83 C<ILS::Item>. The SIP protocol query messages (Patron
84 Information, or Item Status, for example), are implemented within
85 the SIP server code by fetching a Patron, or Item, record and
86 then retrieving the relevant information from that record. See
87 L<ILS::Patron> and L<ILS::Item> for the details.
91 The first thing the SIP server does, after a terminal has
92 successfully logged in, is initialize the ILS module by calling
94 $ils = new ILS $institution
96 where C<$institution> is an object of type
97 C<Sip::Configuration::Institution>, describing the institution to
98 which the terminal belongs. In general, this will be the single
99 institution that the ILS supports, but it may be that in a
100 consortial setting, the SIP server may support connecting to
101 different ILSs based on the C<$institution> of the terminal.
103 =head1 BASIC OBJECT ACCESS AND PROTOCOL SUPPORT
105 The C<$ils> object supports a small set of simple access methods
106 and methods that allow the SIP server to determine if certain
107 protocol operations are permitted to the remote terminals.
109 =head2 C<$inst_name = $self-E<gt>institution;>
111 Returns the institution ID as a string, suitable for
112 incorporating into a SIP response message.
114 =head2 C<$bool = $self-E<gt>support($operation);>
116 Reports whether this ILS implementation supports certain
117 operations that are necessary to report information to the SIP
118 terminal. The argument C<$operation> is a string from this list:
122 =item C<'magnetic media'>
124 Can the ILS properly report whether an item is (or contains)
125 magnetic media, such as a videotape or a book with a floppy disk?
127 =item C<'security inhibit'>
129 Is the ILS capable of directing the terminal to ignore the
130 security status of an item?
132 =item C<'offline operation'>
134 Does the ILS allow self-check units to operate when unconnected
135 to the ILS? That is, can a self-check unit check out items to
136 patrons without checking the status of the items and patrons in
141 =head2 C<$bool = $self-E<gt>checkout_ok;>
143 Are the self service terminals permitted to check items out to
146 =head2 C<$bool = $self-E<gt>checkin_ok;>
148 Are the self service terminals permitted to check items in?
150 =head2 C<$bool = $self-E<gt>status_update_ok;>
152 Are the self service terminals permitted to update patron status
153 information. For example, can terminals block patrons?
155 =head2 C<$bool = $self-E<gt>offline_ok>;
157 Are the self service terminals permitted to operate off-line.
158 That is, can they perform their core self service operations when
159 not in communication with the ILS?
161 =head1 THE TRANSACTIONS
163 In general, every protocol transaction that changes the status of
164 some ILS object (Patron or Item) has a corresponding C<ILS>
165 method. Operations like C<Check In>, which are a function of
166 both a patron and an item are C<ILS> functions, while others,
167 like C<Patron Status> or C<Item Status>, which only depend on one
168 type of object, are methods of the corresponding sub-module.
170 In the stub implementation provided with the SIP system, the
171 C<$status> objects returned by the various C<ILS> transactions
172 are objects that are subclasses of a virtual C<ILS::Transaction>
173 object, but this is not required of the SIP code, as long as the
174 status objects support the appropriate methods.
176 =head2 CORE TRANSACTION STATUS METHODS
178 The C<$status> objects returned by all transactions must support
179 the following common methods:
185 Returns C<true> if the transaction was successful and C<false> if
186 not. Other methods can be used to find out what went wrong.
190 Returns an C<ILS::Item> object corresponding to the item with the
191 barcode C<$item_id>, or C<undef> if the barcode is invalid.
195 Returns a C<ILS::Patron> object corresponding to the patron with
196 the barcode C<$patron_id>, or C<undef> if the barcode is invalid
197 (ie, nonexistent, as opposed to "expired" or "delinquent").
201 Optional. Returns a message that is to be displayed on the
202 terminal's screen. Some self service terminals read the value of
203 this string and act based on it. The configuration of the
204 terminal, and the ILS implementation of this method will have to
209 Optional. Returns a message that is to be printed on the
210 terminal's receipt printer. This message is distinct from the
211 basic transactional information that the terminal will be
212 printing anyway (such as, the basic checkout information like the
217 =head2 C<$status = $ils-E<gt>checkout($patron_id, $item_id, $sc_renew)>
219 Check out (or possibly renew) item with barcode C<$item_id> to
220 the patron with barcode C<$patron_id>. If C<$sc_renew> is true,
221 then the self-check terminal has been configured to allow
222 self-renewal of items, and the ILS may take this into account
223 when deciding how to handle the case where C<$item_id> is already
224 checked out to C<$patron_id>.
226 The C<$status> object returned by C<checkout> must support the
233 Is this transaction actually a renewal? That is, did C<$patron_id>
234 already have C<$item_id> checked out?
238 Should the terminal desensitize the item? This will be false for
239 magnetic media, like videocassettes, and for "in library" items
240 that are checked out to the patron, but not permitted to leave the
243 =item C<security_inhibit>
245 Should self checkout unit ignore the security status of this
248 This method will only be used if
250 $ils->supports('security inhibit')
256 If there is a fee associated with the use of C<$item_id>, then
257 this method should return the amount of the fee, otherwise it
258 should return zero. See also the C<sip_currency> and
259 C<sip_fee_type> methods.
261 =item C<sip_currency>
263 The ISO currency code for the currency in which the fee
264 associated with this item is denominated. For example, 'USD' or
267 =item C<sip_fee_type>
269 A code indicating the type of fee associated with this item. See
270 the table in the protocol specification for the complete list of
271 standard values that this function can return.
275 =head2 C<$status = $ils-E<gt>checkin($item_id, $trans_date, $return_date, $current_loc, $item_props, $cancel)>
277 Check in item identified by barcode C<$item_id>. This
278 transaction took place at time C<$trans_date> and was effective
279 C<$return_date> (to allow for backdating of items to when the
280 branch closed, for example). The self check unit which received
281 the item is located at C<$current_loc>, and the item has
282 properties C<$item_props>. The parameters C<$current_loc> and
283 C<$item_props> are opaque strings passed from the self service
284 unit to the ILS untranslated. The configuration of the terminal,
285 and the ILS implementation of this method will have to be
288 The C<$status> object returned by the C<checkin> operation must
289 support the following methods:
295 Does the item need to be resensitized by the self check unit?
299 Should the self check unit generate an audible alert to notify
300 staff that the item has been returned?
304 Certain self checkin units provide for automated sorting of the
305 returned items. This function returns the bin number into which
306 the received item should be placed. This function may return the
307 empty string, or C<undef>, to indicate that no sort bin has been
312 =head2 C<($status, $screen_msg, $print_line) = $ils-E<gt>end_patron_session($patron_id)>
314 This function informs the ILS that the current patron's session
315 has ended. This allows the ILS to free up any internal state
316 that it may be preserving between messages from the self check
317 unit. The function returns a boolean C<$status>, where C<true>
318 indicates success, and two strings: a screen message to display
319 on the self check unit's console, and a print line to be printed
320 on the unit's receipt printer.
322 =head2 C<$status = $ils-E<gt>pay_fee($patron_id, $patron_pwd, $fee_amt, $fee_type, $pay_type, $fee_id, $trans_id, $currency)>
324 Reports that the self check terminal handled fee payment from
325 patron C<$patron_id> (who has password C<$patron_pwd>, which is
326 an optional parameter). The other parameters are:
332 The amount of the fee.
336 The type of fee, according a table in the SIP protocol
341 The payment method. Defined in the SIP protocol specification.
345 Optional. Identifies which particular fee was paid. This
346 identifier would have been sent from the ILS to the Self Check
347 unit by a previous "Patron Information Response" message.
351 Optional. A transaction identifier set by the payment device.
352 This should be recorded by the ILS for financial tracking
357 An ISO currency code indicating the currency in which the fee was
362 The status object returned by the C<pay_fee> must support the
367 =item C<transaction_id>
369 Transaction identifier of the transaction. This parallels the
370 optional C<$trans_id> sent from the terminal to the ILS. This
371 may return an empty string.
375 =head2 C<$status = $ils-E<gt>add_hold($patron_id, $patron_pwd, $item_id, $title_id, $expiry_date, $pickup_locn, $hold_type, $fee_ack);>
377 Places a hold for C<$patron_id> (optionally, with password
378 C<$patron_pwd>) on the item described by either C<$item_id> or
379 C<$title_id>. The other parameters are:
383 =item C<$expiry_date>
385 The date on which the hold should be cancelled. This date is a
386 SIP protocol standard format timestamp:
390 where the 'Z' characters indicate spaces.
392 =item C<$pickup_location>
394 The location at which the patron wishes to pick up the item when
395 it's available. The configuration of the terminal, and the ILS
396 implementation of this parameter will have to be coordinated.
400 The type of hold being placed: any copy, a specific copy, any
401 copy from a particular branch or location. See the SIP protocol
402 specification for the exact values that this parameter might
407 Boolean. If true, the patron has acknowleged that she is willing
408 to pay the fee associated with placing a hold on this item. If
409 C<$fee_ack> is false, then the ILS should refuse to place the
414 =head2 C<$status = $ils-E<gt>cancel_hold($patron_id, $patron_pwd, $item_id, $title_id);>
416 Cancel a hold placed by C<$patron_id> for the item identified by
417 C<$item_id> or C<$title_id>. The patron password C<$patron_pwd>
418 may be C<undef>, if it was not provided by the terminal.
420 =head2 C<$status = $ils-E<gt>alter_hold($patron_id, $patron_pwd, $item_id, $title_id, $expiry_date, $pickup_locn, $hold_type, $fee_ack);>
422 The C<$status> object returned by C<$ils-E<gt>add_hold>,
423 C<$ils-E<gt>cancel_hold>, and C<$ils-E<gt>alter_hold> must all
424 support the same methods:
428 =item C<expiration_date>
430 Returns the expiry date for the placed hold, in seconds since the
433 =item C<queue_position>
435 Returns the new hold's place in the queue of outstanding holds.
437 =item C<pickup_location>
439 Returns the location code for the pickup location.
443 =head2 C<$status = $ils-E<gt>renew($patron_id, $patron_pwd, $item_id, $title_id, $no_block, $nb_due_date, $third_party, $item_props, $fee_ack);>
445 Renew the item identified by C<$item_id> or C<$title_id>, as
446 requested by C<$patron_id> (with password C<$patron_pwd>). The
447 item has the properties C<$item_props> associated with it.
449 If the patron renewed the item while the terminal was
450 disconnected from the net, then it is a C<$no_block> transaction,
451 and the due date assigned by the terminal, and reported to the
452 patron was C<$nb_due_date> (so we have to honor it).
454 If there is a fee associated with renewing the item, and the
455 patron has agreed to pay the fee, then C<$fee_ack> will be
458 If C<$third_party> is C<'Y'> and the book is not checked out to
459 C<$patron_id>, but to some other person, then this is a
460 third-party renewal; the item should be renewed for the person to
461 whom it is checked out, rather than checking it out to
462 C<$patron_id>, or the renewal should fail.
464 The C<$status> object returned by C<$ils-E<gt>renew> must support
465 the following methods:
471 Boolean. If C<renewal_ok> is true, then the item was already
472 checked out to the patron, so it is being renewed. If
473 C<renewal_ok> is false, then the patron did not already have the
476 NOTE: HOW IS THIS USED IN PRACTICE?
478 =item C<desensitize>, C<security_inhibit>, C<fee_amount>, C<sip_currency>, C<sip_fee_type>, C<transaction_id>
480 See C<$ils-E<gt>checkout> for these methods.
484 =head2 C<$status = $ils-E<gt>renew_all($patron_id, $patron_pwd, $fee_ack);>
486 Renew all items checked out by C<$patron_id> (with password
487 C<$patron_pwd>). If the patron has agreed to pay any fees
488 associated with this transaction, then C<$fee_ack> will be
491 The C<$status> object must support the following methods:
497 Returns a list of the C<$item_id>s of the items that were renewed.
501 Returns a list of the C<$item_id>s of the items that were not renewed.