C4/SIP/ILS.pod

   1 =head1 NAME
   2
   3 ILS - Portability layer to interface between Open-SIP and ILS
   4
   5 =head1 SYNOPSIS
   6
   7     use ILS;
   8
   9     # Initialize connection between SIP and the ILS
  10     my $ils = new ILS (institution => 'Foo Public Library');
  11
  12     # Basic object access methods
  13     $inst_name = $self->institution;
  14     $bool = $self->support($operation);
  15     $self->check_inst_id($inst_name, "error message");
  16
  17     # Check to see if certain protocol options are permitted
  18     $bool = $self->checkout_ok;
  19     $bool = $self->checkin_ok;
  20     $bool = $self->status_update_ok;
  21     $bool = $self->offline_ok;
  22
  23     $status = $ils->checkout($patron_id, $item_id, $sc_renew);
  24
  25     $status = $ils->checkin($item_id, $trans_date, $return_date,
  26                             $current_loc, $item_props, $cancel);
  27
  28     $status = $ils->end_patron_session($patron_id);
  29
  30     $status = $ils->pay_fee($patron_id, $patron_pwd, $fee_amt,
  31                             $fee_type, $pay_type, $fee_id, $trans_id,
  32                             $currency);
  33
  34     $status = $ils->add_hold($patron_id, $patron_pwd, $item_id,
  35                              $title_id, $expiry_date,
  36                              $pickup_locn, $hold_type, $fee_ack);
  37
  38     $status = $ils->cancel_hold($patron_id, $patron_pwd,
  39                                 $item_id, $title_id);
  40
  41     $status = $ils->alter_hold($patron_id, $patron_pwd, $item_id,
  42                                $title_id, $expiry_date,
  43                                $pickup_locn, $hold_type,
  44                                $fee_ack);
  45
  46     $status = $ils->renew($patron_id, $patron_pwd, $item_id,
  47                           $title_id, $no_block, $nb_due_date,
  48                           $third_party, $item_props, $fee_ack);
  49
  50     $status = $ils->renew_all($patron_id, $patron_pwd, $fee_ack);
  51
  52 =head1 INTRODUCTION
  53
  54 The ILS module defines a basic portability layer between the SIP
  55 server and the rest of the integrated library system.  It is the
  56 responsibility of the ILS vendor to implement the functions
  57 defined by this interface.  This allows the SIP server to be
  58 reasonably portable between ILS systems (of course, we won't know
  59 exactly I<how> portable the interface is until it's been used by
  60 a second ILS.
  61
  62 Because no business logic is embedded in the SIP server code
  63 itself, the SIP protocol handler functions do almost nothing
  64 except decode the network messages and pass the parameters to the
  65 ILS module or one of its submodules, C<ILS::Patron> and
  66 C<ILS::Item>.  The SIP protocol query messages (Patron
  67 Information, or Item Status, for example), are implemented within
  68 the SIP server code by fetching a Patron, or Item, record and
  69 then retrieving the relevant information from that record.  See
  70 L<ILS::Patron> and L<ILS::Item> for the details.
  71
  72 =head1 INITIALIZATION
  73
  74 The first thing the SIP server does, after a terminal has
  75 successfully logged in, is initialize the ILS module by calling
  76
  77     $ils = new ILS $institution
  78
  79 where C<$institution> is an object of type
  80 C<Sip::Configuration::Institution>, describing the institution to
  81 which the terminal belongs.  In general, this will be the single
  82 institution that the ILS supports, but it may be that in a
  83 consortial setting, the SIP server may support connecting to
  84 different ILSs based on the C<$institution> of the terminal.
  85
  86 =head1 BASIC OBJECT ACCESS AND PROTOCOL SUPPORT
  87
  88 The C<$ils> object supports a small set of simple access methods
  89 and methods that allow the SIP server to determine if certain
  90 protocol operations are permitted to the remote terminals.
  91
  92 =head2 C<$inst_name = $self-E<gt>institution;>
  93
  94 Returns the institution ID as a string, suitable for
  95 incorporating into a SIP response message.
  96
  97 =head2 C<$bool = $self-E<gt>support($operation);>
  98
  99 Reports whether this ILS implementation supports certain
 100 operations that are necessary to report information to the SIP
 101 terminal. The argument C<$operation> is a string from this list:
 102
 103 =over
 104
 105 =item C<'magnetic media'>
 106
 107 Can the ILS properly report whether an item is (or contains)
 108 magnetic media, such as a videotape or a book with a floppy disk?
 109
 110 =item C<'security inhibit'>
 111
 112 Is the ILS capable of directing the terminal to ignore the
 113 security status of an item?
 114
 115 =item C<'offline operation'>
 116
 117 Does the ILS allow self-check units to operate when unconnected
 118 to the ILS?  That is, can a self-check unit check out items to
 119 patrons without checking the status of the items and patrons in
 120 real time?
 121
 122 =back
 123
 124 =head2 C<$bool = $self-E<gt>checkout_ok;>
 125
 126 Are the self service terminals permitted to check items out to
 127 patrons?
 128
 129 =head2 C<$bool = $self-E<gt>checkin_ok;>
 130
 131 Are the self service terminals permitted to check items in?
 132
 133 =head2 C<$bool = $self-E<gt>status_update_ok;>
 134
 135 Are the self service terminals permitted to update patron status
 136 information.  For example, can terminals block patrons?
 137
 138 =head2 C<$bool = $self-E<gt>offline_ok>;
 139
 140 Are the self service terminals permitted to operate off-line.
 141 That is, can they perform their core self service operations when
 142 not in communication with the ILS?
 143
 144 =head1 THE TRANSACTIONS
 145
 146 In general, every protocol transaction that changes the status of
 147 some ILS object (Patron or Item) has a corresponding C<ILS>
 148 method.  Operations like C<Check In>, which are a function of
 149 both a patron and an item are C<ILS> functions, while others,
 150 like C<Patron Status> or C<Item Status>, which only depend on one
 151 type of object, are methods of the corresponding sub-module.
 152
 153 In the stub implementation provided with the SIP system, the
 154 C<$status> objects returned by the various C<ILS> transactions
 155 are objects that are subclasses of a virtual C<ILS::Transaction>
 156 object, but this is not required of the SIP code, as long as the
 157 status objects support the appropriate methods.
 158
 159 =head2 CORE TRANSACTION STATUS METHODS
 160
 161 The C<$status> objects returned by all transactions must support
 162 the following common methods:
 163
 164 =over
 165
 166 =item C<ok>
 167
 168 Returns C<true> if the transaction was successful and C<false> if
 169 not.  Other methods can be used to find out what went wrong.
 170
 171 =item C<item>
 172
 173 Returns an C<ILS::Item> object corresponding to the item with the
 174 barcode C<$item_id>, or C<undef> if the barcode is invalid.
 175
 176 =item C<patron>
 177
 178 Returns a C<ILS::Patron> object corresponding to the patron with
 179 the barcode C<$patron_id>, or C<undef> if the barcode is invalid
 180 (ie, nonexistent, as opposed to "expired" or "delinquent").
 181
 182 =item C<screen_msg>
 183
 184 Optional. Returns a message that is to be displayed on the
 185 terminal's screen.  Some self service terminals read the value of
 186 this string and act based on it.  The configuration of the
 187 terminal, and the ILS implementation of this method will have to
 188 be coordinated.
 189
 190 =item C<print_line>
 191
 192 Optional.  Returns a message that is to be printed on the
 193 terminal's receipt printer.  This message is distinct from the
 194 basic transactional information that the terminal will be
 195 printing anyway (such as, the basic checkout information like the
 196 title and due date).
 197
 198 =back
 199
 200 =head2 C<$status = $ils-E<gt>checkout($patron_id, $item_id, $sc_renew)>
 201
 202 Check out (or possibly renew) item with barcode C<$item_id> to
 203 the patron with barcode C<$patron_id>.  If C<$sc_renew> is true,
 204 then the self-check terminal has been configured to allow
 205 self-renewal of items, and the ILS may take this into account
 206 when deciding how to handle the case where C<$item_id> is already
 207 checked out to C<$patron_id>.
 208
 209 The C<$status> object returned by C<checkout> must support the
 210 following methods:
 211
 212 =over
 213
 214 =item C<renewal_ok>
 215
 216 Is this transaction actually a renewal?  That is, did C<$patron_id>
 217 already have C<$item_id> checked out?
 218
 219 =item C<desensitize>
 220
 221 Should the terminal desensitize the item?  This will be false for
 222 magnetic media, like videocassettes, and for "in library" items
 223 that are checked out to the patron, but not permitted to leave the
 224 building.
 225
 226 =item C<security_inhibit>
 227
 228 Should self checkout unit ignore the security status of this
 229 item?
 230
 231 This method will only be used if
 232
 233     $ils->supports('security inhibit')
 234
 235 returns C<true>.
 236
 237 =item C<fee_amount>
 238
 239 If there is a fee associated with the use of C<$item_id>, then
 240 this method should return the amount of the fee, otherwise it
 241 should return zero.  See also the C<sip_currency> and
 242 C<sip_fee_type> methods.
 243
 244 =item C<sip_currency>
 245
 246 The ISO currency code for the currency in which the fee
 247 associated with this item is denominated.  For example, 'USD' or
 248 'CAD'.
 249
 250 =item C<sip_fee_type>
 251
 252 A code indicating the type of fee associated with this item.  See
 253 the table in the protocol specification for the complete list of
 254 standard values that this function can return.
 255
 256 =back
 257
 258 =head2 C<$status = $ils-E<gt>checkin($item_id, $trans_date, $return_date, $current_loc, $item_props, $cancel)>
 259
 260 Check in item identified by barcode C<$item_id>.  This
 261 transaction took place at time C<$trans_date> and was effective
 262 C<$return_date> (to allow for backdating of items to when the
 263 branch closed, for example). The self check unit which received
 264 the item is located at C<$current_loc>, and the item has
 265 properties C<$item_props>.  The parameters C<$current_loc> and
 266 C<$item_props> are opaque strings passed from the self service
 267 unit to the ILS untranslated.  The configuration of the terminal,
 268 and the ILS implementation of this method will have to be
 269 coordinated.
 270
 271 The C<$status> object returned by the C<checkin> operation must
 272 support the following methods:
 273
 274 =over
 275
 276 =item C<resensitize>
 277
 278 Does the item need to be resensitized by the self check unit?
 279
 280 =item C<alert>
 281
 282 Should the self check unit generate an audible alert to notify
 283 staff that the item has been returned?
 284
 285 =item C<sort_bin>
 286
 287 Certain self checkin units provide for automated sorting of the
 288 returned items.  This function returns the bin number into which
 289 the received item should be placed.  This function may return the
 290 empty string, or C<undef>, to indicate that no sort bin has been
 291 specified.
 292
 293 =back
 294
 295 =head2 C<($status, $screen_msg, $print_line) = $ils-E<gt>end_patron_session($patron_id)>
 296
 297 This function informs the ILS that the current patron's session
 298 has ended.  This allows the ILS to free up any internal state
 299 that it may be preserving between messages from the self check
 300 unit.  The function returns a boolean C<$status>, where C<true>
 301 indicates success, and two strings: a screen message to display
 302 on the self check unit's console, and a print line to be printed
 303 on the unit's receipt printer.
 304
 305 =head2 C<$status = $ils-E<gt>pay_fee($patron_id, $patron_pwd, $fee_amt, $fee_type, $pay_type, $fee_id, $trans_id, $currency)>
 306
 307 Reports that the self check terminal handled fee payment from
 308 patron C<$patron_id> (who has password C<$patron_pwd>, which is
 309 an optional parameter).  The other parameters are:
 310
 311 =over
 312
 313 =item C<$fee_amt>
 314
 315 The amount of the fee.
 316
 317 =item C<$fee_type>
 318
 319 The type of fee, according a table in the SIP protocol
 320 specification.
 321
 322 =item C<$pay_type>
 323
 324 The payment method.  Defined in the SIP protocol specification.
 325
 326 =item C<$fee_id>
 327
 328 Optional. Identifies which particular fee was paid.  This
 329 identifier would have been sent from the ILS to the Self Check
 330 unit by a previous "Patron Information Response" message.
 331
 332 =item C<$trans_id>
 333
 334 Optional. A transaction identifier set by the payment device.
 335 This should be recorded by the ILS for financial tracking
 336 purposes.
 337
 338 =item C<$currency>
 339
 340 An ISO currency code indicating the currency in which the fee was
 341 paid.
 342
 343 =back
 344
 345 The status object returned by the C<pay_fee> must support the
 346 following methods:
 347
 348 =over
 349
 350 =item C<transaction_id>
 351
 352 Transaction identifier of the transaction.  This parallels the
 353 optional C<$trans_id> sent from the terminal to the ILS.  This
 354 may return an empty string.
 355
 356 =back
 357
 358 =head2 C<$status = $ils-E<gt>add_hold($patron_id, $patron_pwd, $item_id, $title_id, $expiry_date, $pickup_locn, $hold_type, $fee_ack);>
 359
 360 Places a hold for C<$patron_id> (optionally, with password
 361 C<$patron_pwd>) on the item described by either C<$item_id> or
 362 C<$title_id>. The other parameters are:
 363
 364 =over
 365
 366 =item C<$expiry_date>
 367
 368 The date on which the hold should be cancelled.  This date is a
 369 SIP protocol standard format timestamp:
 370
 371     YYYYMMDDZZZZHHMMSS
 372
 373 where the 'Z' characters indicate spaces.
 374
 375 =item C<$pickup_location>
 376
 377 The location at which the patron wishes to pick up the item when
 378 it's available.  The configuration of the terminal, and the ILS
 379 implementation of this parameter will have to be coordinated.
 380
 381 =item C<$hold_type>
 382
 383 The type of hold being placed: any copy, a specific copy, any
 384 copy from a particular branch or location.  See the SIP protocol
 385 specification for the exact values that this parameter might
 386 take.
 387
 388 =item C<$fee_ack>
 389
 390 Boolean.  If true, the patron has acknowleged that she is willing
 391 to pay the fee associated with placing a hold on this item.  If
 392 C<$fee_ack> is false, then the ILS should refuse to place the
 393 hold.
 394
 395 =back
 396
 397 =head2 C<$status = $ils-E<gt>cancel_hold($patron_id, $patron_pwd, $item_id, $title_id);>
 398
 399 Cancel a hold placed by C<$patron_id> for the item identified by
 400 C<$item_id> or C<$title_id>.  The patron password C<$patron_pwd>
 401 may be C<undef>, if it was not provided by the terminal.
 402
 403 =head2 C<$status = $ils-E<gt>alter_hold($patron_id, $patron_pwd, $item_id, $title_id, $expiry_date, $pickup_locn, $hold_type, $fee_ack);>
 404
 405 The C<$status> object returned by C<$ils-E<gt>add_hold>,
 406 C<$ils-E<gt>cancel_hold>, and C<$ils-E<gt>alter_hold> must all
 407 support the same methods:
 408
 409 =over
 410
 411 =item C<expiration_date>
 412
 413 Returns the expiry date for the placed hold, in seconds since the
 414 epoch.
 415
 416 =item C<queue_position>
 417
 418 Returns the new hold's place in the queue of outstanding holds.
 419
 420 =item C<pickup_location>
 421
 422 Returns the location code for the pickup location.
 423
 424 =back
 425
 426 =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);>
 427
 428 Renew the item identified by C<$item_id> or C<$title_id>, as
 429 requested by C<$patron_id> (with password C<$patron_pwd>).  The
 430 item has the properties C<$item_props> associated with it.
 431
 432 If the patron renewed the item while the terminal was
 433 disconnected from the net, then it is a C<$no_block> transaction,
 434 and the due date assigned by the terminal, and reported to the
 435 patron was C<$nb_due_date> (so we have to honor it).
 436
 437 If there is a fee associated with renewing the item, and the
 438 patron has agreed to pay the fee, then C<$fee_ack> will be
 439 C<'Y'>.
 440
 441 If C<$third_party> is C<'Y'> and the book is not checked out to
 442 C<$patron_id>, but to some other person, then this is a
 443 third-party renewal; the item should be renewed for the person to
 444 whom it is checked out, rather than checking it out to
 445 C<$patron_id>, or the renewal should fail.
 446
 447 The C<$status> object returned by C<$ils-E<gt>renew> must support
 448 the following methods:
 449
 450 =over
 451
 452 =item C<renewal_ok>
 453
 454 Boolean.  If C<renewal_ok> is true, then the item was already
 455 checked out to the patron, so it is being renewed.  If
 456 C<renewal_ok> is false, then the patron did not already have the
 457 item checked out.
 458
 459 NOTE: HOW IS THIS USED IN PRACTICE?
 460
 461 =item C<desensitize>, C<security_inhibit>, C<fee_amount>, C<sip_currency>, C<sip_fee_type>, C<transaction_id>
 462
 463 See C<$ils-E<gt>checkout> for these methods.
 464
 465 =back
 466
 467 =head2 C<$status = $ils-E<gt>renew_all($patron_id, $patron_pwd, $fee_ack);>
 468
 469 Renew all items checked out by C<$patron_id> (with password
 470 C<$patron_pwd>).  If the patron has agreed to pay any fees
 471 associated with this transaction, then C<$fee_ack> will be
 472 C<'Y'>.
 473
 474 The C<$status> object must support the following methods:
 475
 476 =over
 477
 478 =item C<renewed>
 479
 480 Returns a list of the C<$item_id>s of the items that were renewed.
 481
 482 =item C<unrenewed>
 483
 484 Returns a list of the C<$item_id>s of the items that were not renewed.
 485
 486 =back