ILS.pod

   1 # Copyright (C) 2006-2008  Georgia Public Library Service
   2 #
   3 # Author: David J. Fiander
   4 #
   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.
   9 #
  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.
  14 #
  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/>.
  17
  18 =head1 NAME
  19
  20 ILS - Portability layer to interface between Open-SIP and ILS
  21
  22 =head1 SYNOPSIS
  23
  24     use ILS;
  25
  26     # Initialize connection between SIP and the ILS
  27     my $ils = new ILS (institution => 'Foo Public Library');
  28
  29     # Basic object access methods
  30     $inst_name = $self->institution;
  31     $bool = $self->support($operation);
  32     $self->check_inst_id($inst_name, "error message");
  33
  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;
  39
  40     $status = $ils->checkout($patron_id, $item_id, $sc_renew);
  41
  42     $status = $ils->checkin($item_id, $trans_date, $return_date,
  43                             $current_loc, $item_props, $cancel);
  44
  45     $status = $ils->end_patron_session($patron_id);
  46
  47     $status = $ils->pay_fee($patron_id, $patron_pwd, $fee_amt,
  48                             $fee_type, $pay_type, $fee_id, $trans_id,
  49                             $currency);
  50
  51     $status = $ils->add_hold($patron_id, $patron_pwd, $item_id,
  52                              $title_id, $expiry_date,
  53                              $pickup_locn, $hold_type, $fee_ack);
  54
  55     $status = $ils->cancel_hold($patron_id, $patron_pwd,
  56                                 $item_id, $title_id);
  57
  58     $status = $ils->alter_hold($patron_id, $patron_pwd, $item_id,
  59                                $title_id, $expiry_date,
  60                                $pickup_locn, $hold_type,
  61                                $fee_ack);
  62
  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);
  66
  67     $status = $ils->renew_all($patron_id, $patron_pwd, $fee_ack);
  68
  69 =head1 INTRODUCTION
  70
  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
  77 a second ILS.
  78
  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.
  88
  89 =head1 INITIALIZATION
  90
  91 The first thing the SIP server does, after a terminal has
  92 successfully logged in, is initialize the ILS module by calling
  93
  94     $ils = new ILS $institution
  95
  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.
 102
 103 =head1 BASIC OBJECT ACCESS AND PROTOCOL SUPPORT
 104
 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.
 108
 109 =head2 C<$inst_name = $self-E<gt>institution;>
 110
 111 Returns the institution ID as a string, suitable for
 112 incorporating into a SIP response message.
 113
 114 =head2 C<$bool = $self-E<gt>support($operation);>
 115
 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:
 119
 120 =over
 121
 122 =item C<'magnetic media'>
 123
 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?
 126
 127 =item C<'security inhibit'>
 128
 129 Is the ILS capable of directing the terminal to ignore the
 130 security status of an item?
 131
 132 =item C<'offline operation'>
 133
 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
 137 real time?
 138
 139 =back
 140
 141 =head2 C<$bool = $self-E<gt>checkout_ok;>
 142
 143 Are the self service terminals permitted to check items out to
 144 patrons?
 145
 146 =head2 C<$bool = $self-E<gt>checkin_ok;>
 147
 148 Are the self service terminals permitted to check items in?
 149
 150 =head2 C<$bool = $self-E<gt>status_update_ok;>
 151
 152 Are the self service terminals permitted to update patron status
 153 information.  For example, can terminals block patrons?
 154
 155 =head2 C<$bool = $self-E<gt>offline_ok>;
 156
 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?
 160
 161 =head1 THE TRANSACTIONS
 162
 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.
 169
 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.
 175
 176 =head2 CORE TRANSACTION STATUS METHODS
 177
 178 The C<$status> objects returned by all transactions must support
 179 the following common methods:
 180
 181 =over
 182
 183 =item C<ok>
 184
 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.
 187
 188 =item C<item>
 189
 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.
 192
 193 =item C<patron>
 194
 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").
 198
 199 =item C<screen_msg>
 200
 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
 205 be coordinated.
 206
 207 =item C<print_line>
 208
 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
 213 title and due date).
 214
 215 =back
 216
 217 =head2 C<$status = $ils-E<gt>checkout($patron_id, $item_id, $sc_renew)>
 218
 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>.
 225
 226 The C<$status> object returned by C<checkout> must support the
 227 following methods:
 228
 229 =over
 230
 231 =item C<renewal_ok>
 232
 233 Is this transaction actually a renewal?  That is, did C<$patron_id>
 234 already have C<$item_id> checked out?
 235
 236 =item C<desensitize>
 237
 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
 241 building.
 242
 243 =item C<security_inhibit>
 244
 245 Should self checkout unit ignore the security status of this
 246 item?
 247
 248 This method will only be used if
 249
 250     $ils->supports('security inhibit')
 251
 252 returns C<true>.
 253
 254 =item C<fee_amount>
 255
 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.
 260
 261 =item C<sip_currency>
 262
 263 The ISO currency code for the currency in which the fee
 264 associated with this item is denominated.  For example, 'USD' or
 265 'CAD'.
 266
 267 =item C<sip_fee_type>
 268
 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.
 272
 273 =back
 274
 275 =head2 C<$status = $ils-E<gt>checkin($item_id, $trans_date, $return_date, $current_loc, $item_props, $cancel)>
 276
 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
 286 coordinated.
 287
 288 The C<$status> object returned by the C<checkin> operation must
 289 support the following methods:
 290
 291 =over
 292
 293 =item C<resensitize>
 294
 295 Does the item need to be resensitized by the self check unit?
 296
 297 =item C<alert>
 298
 299 Should the self check unit generate an audible alert to notify
 300 staff that the item has been returned?
 301
 302 =item C<sort_bin>
 303
 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
 308 specified.
 309
 310 =back
 311
 312 =head2 C<($status, $screen_msg, $print_line) = $ils-E<gt>end_patron_session($patron_id)>
 313
 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.
 321
 322 =head2 C<$status = $ils-E<gt>pay_fee($patron_id, $patron_pwd, $fee_amt, $fee_type, $pay_type, $fee_id, $trans_id, $currency)>
 323
 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:
 327
 328 =over
 329
 330 =item C<$fee_amt>
 331
 332 The amount of the fee.
 333
 334 =item C<$fee_type>
 335
 336 The type of fee, according a table in the SIP protocol
 337 specification.
 338
 339 =item C<$pay_type>
 340
 341 The payment method.  Defined in the SIP protocol specification.
 342
 343 =item C<$fee_id>
 344
 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.
 348
 349 =item C<$trans_id>
 350
 351 Optional. A transaction identifier set by the payment device.
 352 This should be recorded by the ILS for financial tracking
 353 purposes.
 354
 355 =item C<$currency>
 356
 357 An ISO currency code indicating the currency in which the fee was
 358 paid.
 359
 360 =back
 361
 362 The status object returned by the C<pay_fee> must support the
 363 following methods:
 364
 365 =over
 366
 367 =item C<transaction_id>
 368
 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.
 372
 373 =back
 374
 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);>
 376
 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:
 380
 381 =over
 382
 383 =item C<$expiry_date>
 384
 385 The date on which the hold should be cancelled.  This date is a
 386 SIP protocol standard format timestamp:
 387
 388     YYYYMMDDZZZZHHMMSS
 389
 390 where the 'Z' characters indicate spaces.
 391
 392 =item C<$pickup_location>
 393
 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.
 397
 398 =item C<$hold_type>
 399
 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
 403 take.
 404
 405 =item C<$fee_ack>
 406
 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
 410 hold.
 411
 412 =back
 413
 414 =head2 C<$status = $ils-E<gt>cancel_hold($patron_id, $patron_pwd, $item_id, $title_id);>
 415
 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.
 419
 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);>
 421
 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:
 425
 426 =over
 427
 428 =item C<expiration_date>
 429
 430 Returns the expiry date for the placed hold, in seconds since the
 431 epoch.
 432
 433 =item C<queue_position>
 434
 435 Returns the new hold's place in the queue of outstanding holds.
 436
 437 =item C<pickup_location>
 438
 439 Returns the location code for the pickup location.
 440
 441 =back
 442
 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);>
 444
 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.
 448
 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).
 453
 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
 456 C<'Y'>.
 457
 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.
 463
 464 The C<$status> object returned by C<$ils-E<gt>renew> must support
 465 the following methods:
 466
 467 =over
 468
 469 =item C<renewal_ok>
 470
 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
 474 item checked out.
 475
 476 NOTE: HOW IS THIS USED IN PRACTICE?
 477
 478 =item C<desensitize>, C<security_inhibit>, C<fee_amount>, C<sip_currency>, C<sip_fee_type>, C<transaction_id>
 479
 480 See C<$ils-E<gt>checkout> for these methods.
 481
 482 =back
 483
 484 =head2 C<$status = $ils-E<gt>renew_all($patron_id, $patron_pwd, $fee_ack);>
 485
 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
 489 C<'Y'>.
 490
 491 The C<$status> object must support the following methods:
 492
 493 =over
 494
 495 =item C<renewed>
 496
 497 Returns a list of the C<$item_id>s of the items that were renewed.
 498
 499 =item C<unrenewed>
 500
 501 Returns a list of the C<$item_id>s of the items that were not renewed.
 502
 503 =back