From: djfiander Date: Mon, 15 May 2006 00:14:27 +0000 (+0000) Subject: Finish first pass at documentation for ILS module X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=62d6c7714dcc1865bcc7e3799e17b8b7b4cfdb60;p=working%2FSIPServer.git Finish first pass at documentation for ILS module --- diff --git a/ILS.pod b/ILS.pod index 07198ac..8ff3b46 100644 --- a/ILS.pod +++ b/ILS.pod @@ -1,5 +1,3 @@ -=for comment -*- text -*- - =head1 NAME ILS - Portability layer to interface between Open-SIP and ILS @@ -11,26 +9,46 @@ ILS - Portability layer to interface between Open-SIP and ILS # Initialize connection between SIP and the ILS my $ils = new ILS (institution => 'Foo Public Library'); - # Look up a patron based on barcode/id and return status - my $patron = new ILS::Patron $patron_id; + # Basic object access methods + $inst_name = $self->institution; + $bool = $self->support($operation); + $self->check_inst_id($inst_name, "error message"); - # Look up item based on barcode and return status - my $item = new ILS::Item $patron_id; + # Check to see if certain protocol options are permitted + $bool = $self->checkout_ok; + $bool = $self->checkin_ok; + $bool = $self->status_update_ok; + $bool = $self->offline_ok; $status = $ils->checkout($patron_id, $item_id, $sc_renew); $status = $ils->checkin($item_id, $trans_date, $return_date, $current_loc, $item_props, $cancel); - $status = $ils->block_patron($patron_id, $card_retained, - $blocked_card_msg); - $status = $ils->end_patron_session($patron_id); $status = $ils->pay_fee($patron_id, $patron_pwd, $fee_amt, $fee_type, $pay_type, $fee_id, $trans_id, $currency); + $status = $ils->add_hold($patron_id, $patron_pwd, $item_id, + $title_id, $expiry_date, + $pickup_locn, $hold_type, $fee_ack); + + $status = $ils->cancel_hold($patron_id, $patron_pwd, + $item_id, $title_id); + + $status = $ils->alter_hold($patron_id, $patron_pwd, $item_id, + $title_id, $expiry_date, + $pickup_locn, $hold_type, + $fee_ack); + + $status = $ils->renew($patron_id, $patron_pwd, $item_id, + $title_id, $no_block, $nb_due_date, + $third_party, $item_props, $fee_ack); + + $status = $ils->renew_all($patron_id, $patron_pwd, $fee_ack); + =head1 INTRODUCTION The ILS module defines a basic portability layer between the SIP @@ -45,7 +63,11 @@ Because no business logic is embedded in the SIP server code itself, the SIP protocol handler functions do almost nothing except decode the network messages and pass the parameters to the ILS module or one of its submodules, C and -C. +C. The SIP protocol query messages (Patron +Information, or Item Status, for example), are implemented within +the SIP server code by fetching a Patron, or Item, record and +then retrieving the relevant information from that record. See +L and L for the details. =head1 INITIALIZATION @@ -54,26 +76,127 @@ successfully logged in, is initialize the ILS module by calling $ils = new ILS $institution -where C<$institution> is the name of the institution to which the -terminal belongs. In general, this will be the single +where C<$institution> is an object of type +C, describing the institution to +which the terminal belongs. In general, this will be the single institution that the ILS supports, but it may be that in a consortial setting, the SIP server may support connecting to different ILSs based on the C<$institution> of the terminal. +=head1 BASIC OBJECT ACCESS AND PROTOCOL SUPPORT + +The C<$ils> object supports a small set of simple access methods +and methods that allow the SIP server to determine if certain +protocol operations are permitted to the remote terminals. + +=head2 C<$inst_name = $self-Einstitution;> + +Returns the institution ID as a string, suitable for +incorporating into a SIP response message. + +=head2 C<$bool = $self-Esupport($operation);> + +Reports whether this ILS implementation supports certain +operations that are necessary to report information to the SIP +terminal. The argument C<$operation> is a string from this list: + +=over + +=item C<'magnetic media'> + +Can the ILS properly report whether an item is (or contains) +magnetic media, such as a videotape or a book with a floppy disk? + +=item C<'security inhibit'> + +Is the ILS capable of directing the terminal to ignore the +security status of an item? + +=item C<'offline operation'> + +Does the ILS allow self-check units to operate when unconnected +to the ILS? That is, can a self-check unit check out items to +patrons without checking the status of the items and patrons in +real time? + +=back + +=head2 C<$bool = $self-Echeckout_ok;> + +Are the self service terminals permitted to check items out to +patrons? + +=head2 C<$bool = $self-Echeckin_ok;> + +Are the self service terminals permitted to check items in? + +=head2 C<$bool = $self-Estatus_update_ok;> + +Are the self service terminals permitted to update patron status +information. For example, can terminals block patrons? + +=head2 C<$bool = $self-Eoffline_ok>; + +Are the self service terminals permitted to operate off-line. +That is, can they perform their core self service operations when +not in communication with the ILS? + =head1 THE TRANSACTIONS -In general, every protocol transaction has a corresponding C -function. Operations like C, which are a function of a -patron and an item are C functions, while others, like -C or C, are functions of the -corresponding sub-module. +In general, every protocol transaction that changes the status of +some ILS object (Patron or Item) has a corresponding C +method. Operations like C, which are a function of +both a patron and an item are C functions, while others, +like C or C, which only depend on one +type of object, are methods of the corresponding sub-module. In the stub implementation provided with the SIP system, the -C<$status> objects returned by the various transactions are all -objects that are subclasses of a virtual C +C<$status> objects returned by the various C transactions +are objects that are subclasses of a virtual C object, but this is not required of the SIP code, as long as the status objects support the appropriate methods. +=head2 CORE TRANSACTION STATUS METHODS + +The C<$status> objects returned by all transactions must support +the following common methods: + +=over + +=item C + +Returns C if the transaction was successful and C if +not. Other methods can be used to find out what went wrong. + +=item C + +Returns an C object corresponding to the item with the +barcode C<$item_id>, or C if the barcode is invalid. + +=item C + +Returns a C object corresponding to the patron with +the barcode C<$patron_id>, or C if the barcode is invalid +(ie, nonexistent, as opposed to "expired" or "delinquent"). + +=item C + +Optional. Returns a message that is to be displayed on the +terminal's screen. Some self service terminals read the value of +this string and act based on it. The configuration of the +terminal, and the ILS implementation of this method will have to +be coordinated. + +=item C + +Optional. Returns a message that is to be printed on the +terminal's receipt printer. This message is distinct from the +basic transactional information that the terminal will be +printing anyway (such as, the basic checkout information like the +title and due date). + +=back + =head2 C<$status = $ils-Echeckout($patron_id, $item_id, $sc_renew)> Check out (or possibly renew) item with barcode C<$item_id> to @@ -88,46 +211,47 @@ following methods: =over -=item C +=item C -Returns C if the transaction was successful and C if -not. Other methods can be used to find out what went wrong. +Is this transaction actually a renewal? That is, did C<$patron_id> +already have C<$item_id> checked out? -=item C +=item C -Returns an C object corresponding to the item with the -barcode C<$item_id>, or C if the barcode is invalid. +Should the terminal desensitize the item? This will be false for +magnetic media, like videocassettes, and for "in library" items +that are checked out to the patron, but not permitted to leave the +building. -=item C +=item C -Returns a C object corresponding to the patron with -the barcode C<$patron_id>, or C if the barcode is invalid. +Should self checkout unit ignore the security status of this +item? -=item C +This method will only be used if -Is this transaction actually a renewal? + $ils->supports('security inhibit') -=item C +returns C. -Boolean: should the terminal desensitize the item? This will be -false for magnetic media, like videocassettes, and for "in -library" items that are checked to the patron, but not permitted -to leave the building. +=item C -=item C +If there is a fee associated with the use of C<$item_id>, then +this method should return the amount of the fee, otherwise it +should return zero. See also the C and +C methods. -SIP formatted timestamp string indicating when the item is due -back. +=item C -=item C +The ISO currency code for the currency in which the fee +associated with this item is denominated. For example, 'USD' or +'CAD'. -Optional. Returns a message that is to be displayed on the -terminal's screen. +=item C -=item C - -Optional. Returns a message that is to be printed on the -terminal's receipt printer. +A code indicating the type of fee associated with this item. See +the table in the protocol specification for the complete list of +standard values that this function can return. =back @@ -138,42 +262,26 @@ transaction took place at time C<$trans_date> and was effective C<$return_date> (to allow for backdating of items to when the branch closed, for example). The self check unit which received the item is located at C<$current_loc>, and the item has -properties C<$item_props>. +properties C<$item_props>. The parameters C<$current_loc> and +C<$item_props> are opaque strings passed from the self service +unit to the ILS untranslated. The configuration of the terminal, +and the ILS implementation of this method will have to be +coordinated. The C<$status> object returned by the C operation must support the following methods: =over -=item C - -Returns C if the transaction was successful and C if -not. Other methods can be used to find out what went wrong. - =item C Does the item need to be resensitized by the self check unit? -=item C - -Is the item some form of magnetic media (eg, a video or a book -with an accompanying floppy)? If this method is defined, it is -assumed to return either C or C for every item. If -there are items for which the ILS does not have "magnetic media" -information, this method may be left undefined, in which case the -SIP code will return 'unknown' for this field to the self-check -unit. - =item C Should the self check unit generate an audible alert to notify staff that the item has been returned? -=item C - -Returns an C object. For more information see -L. - =item C Certain self checkin units provide for automated sorting of the @@ -182,36 +290,8 @@ the received item should be placed. This function may return the empty string, or C, to indicate that no sort bin has been specified. -=item C - -Returns an C object containing information about the -patron who returned the item. For more information see -L. - -=item C - -Optional. Returns a message that is to be displayed on the -terminal's screen. - -=item C - -Optional. Returns a message that is to be printed on the -terminal's receipt printer. - =back -=head2 C<$status = $ils-Eblock_patron($patron_id, $card_retained, $blocked_card_msg);> - -Block the account of the patron identified by C<$patron_id>. If -the self check unit captured the patron's card, then -C<$card_retained> will be C. A message indicating why the -card was retained will be provided by the parameter -C<$blocked_card_msg>. - -This function returns an C object that has been -updated to indicate that the patron's privileges have been -blocked, or C if the patron ID is not valid. - =head2 C<($status, $screen_msg, $print_line) = $ils-Eend_patron_session($patron_id)> This function informs the ILS that the current patron's session @@ -226,8 +306,7 @@ on the unit's receipt printer. Reports that the self check terminal handled fee payment from patron C<$patron_id> (who has password C<$patron_pwd>, which is -an optional parameter). The -other parameters are: +an optional parameter). The other parameters are: =over @@ -258,8 +337,8 @@ purposes. =item C<$currency> -The currency used to pay the fee. Use the three-character -alphabetic codes defined in ISO 4217:1995. +An ISO currency code indicating the currency in which the fee was +paid. =back @@ -268,17 +347,140 @@ following methods: =over -=item C - -Returns C if the fee was properly recorded; C -otherwise. - =item C Transaction identifier of the transaction. This parallels the optional C<$trans_id> sent from the terminal to the ILS. This may return an empty string. -=item C, C +=back + +=head2 C<$status = $ils-Eadd_hold($patron_id, $patron_pwd, $item_id, $title_id, $expiry_date, $pickup_locn, $hold_type, $fee_ack);> + +Places a hold for C<$patron_id> (optionally, with password +C<$patron_pwd>) on the item described by either C<$item_id> or +C<$title_id>. The other parameters are: + +=over + +=item C<$expiry_date> + +The date on which the hold should be cancelled. This date is a +SIP protocol standard format timestamp: + + YYYYMMDDZZZZHHMMSS + +where the 'Z' characters indicate spaces. + +=item C<$pickup_location> + +The location at which the patron wishes to pick up the item when +it's available. The configuration of the terminal, and the ILS +implementation of this parameter will have to be coordinated. + +=item C<$hold_type> + +The type of hold being placed: any copy, a specific copy, any +copy from a particular branch or location. See the SIP protocol +specification for the exact values that this parameter might +take. + +=item C<$fee_ack> + +Boolean. If true, the patron has acknowleged that she is willing +to pay the fee associated with placing a hold on this item. If +C<$fee_ack> is false, then the ILS should refuse to place the +hold. + +=back + +=head2 C<$status = $ils-Ecancel_hold($patron_id, $patron_pwd, $item_id, $title_id);> + +Cancel a hold placed by C<$patron_id> for the item identified by +C<$item_id> or C<$title_id>. The patron password C<$patron_pwd> +may be C, if it was not provided by the terminal. + +=head2 C<$status = $ils-Ealter_hold($patron_id, $patron_pwd, $item_id, $title_id, $expiry_date, $pickup_locn, $hold_type, $fee_ack);> + +The C<$status> object returned by C<$ils-Eadd_hold>, +C<$ils-Ecancel_hold>, and C<$ils-Ealter_hold> must all +support the same methods: + +=over + +=item C + +Returns the expiry date for the placed hold, in seconds since the +epoch. + +=item C + +Returns the new hold's place in the queue of outstanding holds. + +=item C + +Returns the location code for the pickup location. + +=back + +=head2 C<$status = $ils-Erenew($patron_id, $patron_pwd, $item_id, $title_id, $no_block, $nb_due_date, $third_party, $item_props, $fee_ack);> + +Renew the item identified by C<$item_id> or C<$title_id>, as +requested by C<$patron_id> (with password C<$patron_pwd>). The +item has the properties C<$item_props> associated with it. + +If the patron renewed the item while the terminal was +disconnected from the net, then it is a C<$no_block> transaction, +and the due date assigned by the terminal, and reported to the +patron was C<$nb_due_date> (so we have to honor it). + +If there is a fee associated with renewing the item, and the +patron has agreed to pay the fee, then C<$fee_ack> will be +C<'Y'>. + +If C<$third_party> is C<'Y'> and the book is not checked out to +C<$patron_id>, but to some other person, then this is a +third-party renewal; the item should be renewed for the person to +whom it is checked out, rather than checking it out to +C<$patron_id>, or the renewal should fail. + +The C<$status> object returned by C<$ils-Erenew> must support +the following methods: -Defined as for every other transaction. +=over + +=item C + +Boolean. If C is true, then the item was already +checked out to the patron, so it is being renewed. If +C is false, then the patron did not already have the +item checked out. + +NOTE: HOW IS THIS USED IN PRACTICE? + +=item C, C, C, C, C, C + +See C<$ils-Echeckout> for these methods. + +=back + +=head2 C<$status = $ils-Erenew_all($patron_id, $patron_pwd, $fee_ack);> + +Renew all items checked out by C<$patron_id> (with password +C<$patron_pwd>). If the patron has agreed to pay any fees +associated with this transaction, then C<$fee_ack> will be +C<'Y'>. + +The C<$status> object must support the following methods: + +=over + +=item C + +Returns a list of the C<$item_id>s of the items that were renewed. + +=item C + +Returns a list of the C<$item_id>s of the items that were not renewed. + +=back