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