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