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
6 # modify it under the terms of version 2 of the GNU General Public
7 # License as published by the Free Software Foundation.
9 # This program is distributed in the hope that it will be useful,
10 # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 # GNU General Public License for more details.
14 # You should have received a copy of the GNU General Public
15 # License along with this program; if not, write to the Free
16 # Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
21 ILS - Portability layer to interface between Open-SIP and ILS
27 # Initialize connection between SIP and the ILS
28 my $ils = new ILS (institution => 'Foo Public Library');
30 # Basic object access methods
31 $inst_name = $self->institution;
32 $bool = $self->support($operation);
33 $self->check_inst_id($inst_name, "error message");
35 # Check to see if certain protocol options are permitted
36 $bool = $self->checkout_ok;
37 $bool = $self->checkin_ok;
38 $bool = $self->status_update_ok;
39 $bool = $self->offline_ok;
41 $status = $ils->checkout($patron_id, $item_id, $sc_renew);
43 $status = $ils->checkin($item_id, $trans_date, $return_date,
44 $current_loc, $item_props, $cancel);
46 $status = $ils->end_patron_session($patron_id);
48 $status = $ils->pay_fee($patron_id, $patron_pwd, $fee_amt,
49 $fee_type, $pay_type, $fee_id, $trans_id,
52 $status = $ils->add_hold($patron_id, $patron_pwd, $item_id,
53 $title_id, $expiry_date,
54 $pickup_locn, $hold_type, $fee_ack);
56 $status = $ils->cancel_hold($patron_id, $patron_pwd,
59 $status = $ils->alter_hold($patron_id, $patron_pwd, $item_id,
60 $title_id, $expiry_date,
61 $pickup_locn, $hold_type,
64 $status = $ils->renew($patron_id, $patron_pwd, $item_id,
65 $title_id, $no_block, $nb_due_date,
66 $third_party, $item_props, $fee_ack);
68 $status = $ils->renew_all($patron_id, $patron_pwd, $fee_ack);
72 The ILS module defines a basic portability layer between the SIP
73 server and the rest of the integrated library system. It is the
74 responsibility of the ILS vendor to implement the functions
75 defined by this interface. This allows the SIP server to be
76 reasonably portable between ILS systems (of course, we won't know
77 exactly I<how> portable the interface is until it's been used by
80 Because no business logic is embedded in the SIP server code
81 itself, the SIP protocol handler functions do almost nothing
82 except decode the network messages and pass the parameters to the
83 ILS module or one of its submodules, C<ILS::Patron> and
84 C<ILS::Item>. The SIP protocol query messages (Patron
85 Information, or Item Status, for example), are implemented within
86 the SIP server code by fetching a Patron, or Item, record and
87 then retrieving the relevant information from that record. See
88 L<ILS::Patron> and L<ILS::Item> for the details.
92 The first thing the SIP server does, after a terminal has
93 successfully logged in, is initialize the ILS module by calling
95 $ils = new ILS $institution
97 where C<$institution> is an object of type
98 C<Sip::Configuration::Institution>, describing the institution to
99 which the terminal belongs. In general, this will be the single
100 institution that the ILS supports, but it may be that in a
101 consortial setting, the SIP server may support connecting to
102 different ILSs based on the C<$institution> of the terminal.
104 =head1 BASIC OBJECT ACCESS AND PROTOCOL SUPPORT
106 The C<$ils> object supports a small set of simple access methods
107 and methods that allow the SIP server to determine if certain
108 protocol operations are permitted to the remote terminals.
110 =head2 C<$inst_name = $self-E<gt>institution;>
112 Returns the institution ID as a string, suitable for
113 incorporating into a SIP response message.
115 =head2 C<$bool = $self-E<gt>support($operation);>
117 Reports whether this ILS implementation supports certain
118 operations that are necessary to report information to the SIP
119 terminal. The argument C<$operation> is a string from this list:
123 =item C<'magnetic media'>
125 Can the ILS properly report whether an item is (or contains)
126 magnetic media, such as a videotape or a book with a floppy disk?
128 =item C<'security inhibit'>
130 Is the ILS capable of directing the terminal to ignore the
131 security status of an item?
133 =item C<'offline operation'>
135 Does the ILS allow self-check units to operate when unconnected
136 to the ILS? That is, can a self-check unit check out items to
137 patrons without checking the status of the items and patrons in
142 =head2 C<$bool = $self-E<gt>checkout_ok;>
144 Are the self service terminals permitted to check items out to
147 =head2 C<$bool = $self-E<gt>checkin_ok;>
149 Are the self service terminals permitted to check items in?
151 =head2 C<$bool = $self-E<gt>status_update_ok;>
153 Are the self service terminals permitted to update patron status
154 information. For example, can terminals block patrons?
156 =head2 C<$bool = $self-E<gt>offline_ok>;
158 Are the self service terminals permitted to operate off-line.
159 That is, can they perform their core self service operations when
160 not in communication with the ILS?
162 =head1 THE TRANSACTIONS
164 In general, every protocol transaction that changes the status of
165 some ILS object (Patron or Item) has a corresponding C<ILS>
166 method. Operations like C<Check In>, which are a function of
167 both a patron and an item are C<ILS> functions, while others,
168 like C<Patron Status> or C<Item Status>, which only depend on one
169 type of object, are methods of the corresponding sub-module.
171 In the stub implementation provided with the SIP system, the
172 C<$status> objects returned by the various C<ILS> transactions
173 are objects that are subclasses of a virtual C<ILS::Transaction>
174 object, but this is not required of the SIP code, as long as the
175 status objects support the appropriate methods.
177 =head2 CORE TRANSACTION STATUS METHODS
179 The C<$status> objects returned by all transactions must support
180 the following common methods:
186 Returns C<true> if the transaction was successful and C<false> if
187 not. Other methods can be used to find out what went wrong.
191 Returns an C<ILS::Item> object corresponding to the item with the
192 barcode C<$item_id>, or C<undef> if the barcode is invalid.
196 Returns a C<ILS::Patron> object corresponding to the patron with
197 the barcode C<$patron_id>, or C<undef> if the barcode is invalid
198 (ie, nonexistent, as opposed to "expired" or "delinquent").
202 Optional. Returns a message that is to be displayed on the
203 terminal's screen. Some self service terminals read the value of
204 this string and act based on it. The configuration of the
205 terminal, and the ILS implementation of this method will have to
210 Optional. Returns a message that is to be printed on the
211 terminal's receipt printer. This message is distinct from the
212 basic transactional information that the terminal will be
213 printing anyway (such as, the basic checkout information like the
218 =head2 C<$status = $ils-E<gt>checkout($patron_id, $item_id, $sc_renew)>
220 Check out (or possibly renew) item with barcode C<$item_id> to
221 the patron with barcode C<$patron_id>. If C<$sc_renew> is true,
222 then the self-check terminal has been configured to allow
223 self-renewal of items, and the ILS may take this into account
224 when deciding how to handle the case where C<$item_id> is already
225 checked out to C<$patron_id>.
227 The C<$status> object returned by C<checkout> must support the
234 Is this transaction actually a renewal? That is, did C<$patron_id>
235 already have C<$item_id> checked out?
239 Should the terminal desensitize the item? This will be false for
240 magnetic media, like videocassettes, and for "in library" items
241 that are checked out to the patron, but not permitted to leave the
244 =item C<security_inhibit>
246 Should self checkout unit ignore the security status of this
249 This method will only be used if
251 $ils->supports('security inhibit')
257 If there is a fee associated with the use of C<$item_id>, then
258 this method should return the amount of the fee, otherwise it
259 should return zero. See also the C<sip_currency> and
260 C<sip_fee_type> methods.
262 =item C<sip_currency>
264 The ISO currency code for the currency in which the fee
265 associated with this item is denominated. For example, 'USD' or
268 =item C<sip_fee_type>
270 A code indicating the type of fee associated with this item. See
271 the table in the protocol specification for the complete list of
272 standard values that this function can return.
276 =head2 C<$status = $ils-E<gt>checkin($item_id, $trans_date, $return_date, $current_loc, $item_props, $cancel)>
278 Check in item identified by barcode C<$item_id>. This
279 transaction took place at time C<$trans_date> and was effective
280 C<$return_date> (to allow for backdating of items to when the
281 branch closed, for example). The self check unit which received
282 the item is located at C<$current_loc>, and the item has
283 properties C<$item_props>. The parameters C<$current_loc> and
284 C<$item_props> are opaque strings passed from the self service
285 unit to the ILS untranslated. The configuration of the terminal,
286 and the ILS implementation of this method will have to be
289 The C<$status> object returned by the C<checkin> operation must
290 support the following methods:
296 Does the item need to be resensitized by the self check unit?
300 Should the self check unit generate an audible alert to notify
301 staff that the item has been returned?
305 Certain self checkin units provide for automated sorting of the
306 returned items. This function returns the bin number into which
307 the received item should be placed. This function may return the
308 empty string, or C<undef>, to indicate that no sort bin has been
313 =head2 C<($status, $screen_msg, $print_line) = $ils-E<gt>end_patron_session($patron_id)>
315 This function informs the ILS that the current patron's session
316 has ended. This allows the ILS to free up any internal state
317 that it may be preserving between messages from the self check
318 unit. The function returns a boolean C<$status>, where C<true>
319 indicates success, and two strings: a screen message to display
320 on the self check unit's console, and a print line to be printed
321 on the unit's receipt printer.
323 =head2 C<$status = $ils-E<gt>pay_fee($patron_id, $patron_pwd, $fee_amt, $fee_type, $pay_type, $fee_id, $trans_id, $currency)>
325 Reports that the self check terminal handled fee payment from
326 patron C<$patron_id> (who has password C<$patron_pwd>, which is
327 an optional parameter). The other parameters are:
333 The amount of the fee.
337 The type of fee, according a table in the SIP protocol
342 The payment method. Defined in the SIP protocol specification.
346 Optional. Identifies which particular fee was paid. This
347 identifier would have been sent from the ILS to the Self Check
348 unit by a previous "Patron Information Response" message.
352 Optional. A transaction identifier set by the payment device.
353 This should be recorded by the ILS for financial tracking
358 An ISO currency code indicating the currency in which the fee was
363 The status object returned by the C<pay_fee> must support the
368 =item C<transaction_id>
370 Transaction identifier of the transaction. This parallels the
371 optional C<$trans_id> sent from the terminal to the ILS. This
372 may return an empty string.
376 =head2 C<$status = $ils-E<gt>add_hold($patron_id, $patron_pwd, $item_id, $title_id, $expiry_date, $pickup_locn, $hold_type, $fee_ack);>
378 Places a hold for C<$patron_id> (optionally, with password
379 C<$patron_pwd>) on the item described by either C<$item_id> or
380 C<$title_id>. The other parameters are:
384 =item C<$expiry_date>
386 The date on which the hold should be cancelled. This date is a
387 SIP protocol standard format timestamp:
391 where the 'Z' characters indicate spaces.
393 =item C<$pickup_location>
395 The location at which the patron wishes to pick up the item when
396 it's available. The configuration of the terminal, and the ILS
397 implementation of this parameter will have to be coordinated.
401 The type of hold being placed: any copy, a specific copy, any
402 copy from a particular branch or location. See the SIP protocol
403 specification for the exact values that this parameter might
408 Boolean. If true, the patron has acknowleged that she is willing
409 to pay the fee associated with placing a hold on this item. If
410 C<$fee_ack> is false, then the ILS should refuse to place the
415 =head2 C<$status = $ils-E<gt>cancel_hold($patron_id, $patron_pwd, $item_id, $title_id);>
417 Cancel a hold placed by C<$patron_id> for the item identified by
418 C<$item_id> or C<$title_id>. The patron password C<$patron_pwd>
419 may be C<undef>, if it was not provided by the terminal.
421 =head2 C<$status = $ils-E<gt>alter_hold($patron_id, $patron_pwd, $item_id, $title_id, $expiry_date, $pickup_locn, $hold_type, $fee_ack);>
423 The C<$status> object returned by C<$ils-E<gt>add_hold>,
424 C<$ils-E<gt>cancel_hold>, and C<$ils-E<gt>alter_hold> must all
425 support the same methods:
429 =item C<expiration_date>
431 Returns the expiry date for the placed hold, in seconds since the
434 =item C<queue_position>
436 Returns the new hold's place in the queue of outstanding holds.
438 =item C<pickup_location>
440 Returns the location code for the pickup location.
444 =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);>
446 Renew the item identified by C<$item_id> or C<$title_id>, as
447 requested by C<$patron_id> (with password C<$patron_pwd>). The
448 item has the properties C<$item_props> associated with it.
450 If the patron renewed the item while the terminal was
451 disconnected from the net, then it is a C<$no_block> transaction,
452 and the due date assigned by the terminal, and reported to the
453 patron was C<$nb_due_date> (so we have to honor it).
455 If there is a fee associated with renewing the item, and the
456 patron has agreed to pay the fee, then C<$fee_ack> will be
459 If C<$third_party> is C<'Y'> and the book is not checked out to
460 C<$patron_id>, but to some other person, then this is a
461 third-party renewal; the item should be renewed for the person to
462 whom it is checked out, rather than checking it out to
463 C<$patron_id>, or the renewal should fail.
465 The C<$status> object returned by C<$ils-E<gt>renew> must support
466 the following methods:
472 Boolean. If C<renewal_ok> is true, then the item was already
473 checked out to the patron, so it is being renewed. If
474 C<renewal_ok> is false, then the patron did not already have the
477 NOTE: HOW IS THIS USED IN PRACTICE?
479 =item C<desensitize>, C<security_inhibit>, C<fee_amount>, C<sip_currency>, C<sip_fee_type>, C<transaction_id>
481 See C<$ils-E<gt>checkout> for these methods.
485 =head2 C<$status = $ils-E<gt>renew_all($patron_id, $patron_pwd, $fee_ack);>
487 Renew all items checked out by C<$patron_id> (with password
488 C<$patron_pwd>). If the patron has agreed to pay any fees
489 associated with this transaction, then C<$fee_ack> will be
492 The C<$status> object must support the following methods:
498 Returns a list of the C<$item_id>s of the items that were renewed.
502 Returns a list of the C<$item_id>s of the items that were not renewed.