From b085ed16e07030aa0ba1df6abf74166990ec3b6c Mon Sep 17 00:00:00 2001 From: Jonathan Druart Date: Tue, 18 Mar 2025 15:03:52 +0100 Subject: [PATCH] Bug 39367: Remove .pod files from C4/SIP Include them into the pm instead. --- C4/SIP/ILS.pm | 578 ++++++++++++++++++++++++++++++++++++++---- C4/SIP/ILS.pod | 485 ----------------------------------- C4/SIP/ILS/Item.pm | 233 ++++++++++++++++- C4/SIP/ILS/Item.pod | 232 ----------------- C4/SIP/ILS/Patron.pm | 212 ++++++++++++++++ C4/SIP/ILS/Patron.pod | 210 --------------- C4/SIP/Sip.pm | 6 + 7 files changed, 974 insertions(+), 982 deletions(-) delete mode 100644 C4/SIP/ILS.pod delete mode 100644 C4/SIP/ILS/Item.pod delete mode 100644 C4/SIP/ILS/Patron.pod diff --git a/C4/SIP/ILS.pm b/C4/SIP/ILS.pm index dec0a590c3d..0f8e679f3dd 100644 --- a/C4/SIP/ILS.pm +++ b/C4/SIP/ILS.pm @@ -47,16 +47,6 @@ my %supports = ( "renew all" => 1, ); -=head1 Functions - -=cut - -=head2 new - -Missing POD for new. - -=cut - sub new { my ( $class, $institution ) = @_; my $type = ref($class) || $class; @@ -66,23 +56,11 @@ sub new { return bless $self, $type; } -=head2 find_patron - -Missing POD for find_patron. - -=cut - sub find_patron { my $self = shift; return C4::SIP::ILS::Patron->new(@_); } -=head2 find_item - -Missing POD for find_item. - -=cut - sub find_item { my $self = shift; return C4::SIP::ILS::Item->new(@_); @@ -93,34 +71,16 @@ sub institution { return $self->{institution}->{id}; # consider making this return the whole institution } -=head2 institution_id - -Missing POD for institution_id. - -=cut - sub institution_id { my $self = shift; return $self->{institution}->{id}; } -=head2 supports - -Missing POD for supports. - -=cut - sub supports { my ( $self, $op ) = @_; return ( exists( $supports{$op} ) && $supports{$op} ); } -=head2 check_inst_id - -Missing POD for check_inst_id. - -=cut - sub check_inst_id { my ( $self, $id, $whence ) = @_; if ( $id ne $self->{institution}->{id} ) { @@ -133,12 +93,6 @@ sub check_inst_id { } } -=head2 to_bool - -Missing POD for to_bool. - -=cut - sub to_bool { my $bool = shift; @@ -180,7 +134,7 @@ sub offline_ok { # returns a status opject that can be queried for the various bits # of information that the protocol (SIP or NCIP) needs to generate # the response. -# + sub checkout { my ( $self, $patron_id, $item_id, $sc_renew, $fee_ack, $account, $no_block_due_date ) = @_; my ( $patron, $item, $circ ); @@ -289,12 +243,6 @@ sub _ci_cardnumber_cmp { # wrapper which allows above to be called for testing -=head2 test_cardnumber_compare - -Missing POD for test_cardnumber_compare. - -=cut - sub test_cardnumber_compare { my ( $self, $str1, $str2 ) = @_; return _ci_cardnumber_cmp( $str1, $str2 ); @@ -399,6 +347,7 @@ sub checkin { # If the ILS caches patron information, this lets it free # it up + sub end_patron_session { my ( $self, $patron_id ) = @_; @@ -534,6 +483,7 @@ sub cancel_hold { # The patron and item id's can't be altered, but the # date, location, and type can. + sub alter_hold { my ( $self, $patron_id, $patron_pwd, $item_id, $title_id, @@ -680,5 +630,525 @@ sub renew_all { } 1; -__END__ +=head1 NAME + +ILS - Portability layer to interface between Open-SIP and ILS + +=head1 SYNOPSIS + + use ILS; + + # Initialize connection between SIP and the ILS + my $ils = new ILS (institution => 'Foo Public Library'); + + # Basic object access methods + $inst_name = $self->institution; + $bool = $self->support($operation); + $self->check_inst_id($inst_name, "error message"); + + # 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->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 +server and the rest of the integrated library system. It is the +responsibility of the ILS vendor to implement the functions +defined by this interface. This allows the SIP server to be +reasonably portable between ILS systems (of course, we won't know +exactly I portable the interface is until it's been used by +a second ILS. + +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. 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 + +The first thing the SIP server does, after a terminal has +successfully logged in, is initialize the ILS module by calling + + $ils = new ILS $institution + +where C<$institution> is a hash ( institution => 'Foo Public Library' ) +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 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 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 +the patron with barcode C<$patron_id>. If C<$sc_renew> is true, +then the self-check terminal has been configured to allow +self-renewal of items, and the ILS may take this into account +when deciding how to handle the case where C<$item_id> is already +checked out to C<$patron_id>. + +The C<$status> object returned by C must support the +following methods: + +=over + +=item C + +Is this transaction actually a renewal? That is, did C<$patron_id> +already have C<$item_id> checked out? + +=item C + +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 + +Should self checkout unit ignore the security status of this +item? + +This method will only be used if + + $ils->supports('security inhibit') + +returns 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. + +=item C + +The ISO currency code for the currency in which the fee +associated with this item is denominated. For example, 'USD' or +'CAD'. + +=item C + +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 + +=head2 C<$status = $ils-Echeckin($item_id, $trans_date, $return_date, $current_loc, $item_props, $cancel)> + +Check in item identified by barcode C<$item_id>. This +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>. 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 + +Does the item need to be resensitized by 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 + +Certain self checkin units provide for automated sorting of the +returned items. This function returns the bin number into which +the received item should be placed. This function may return the +empty string, or C, to indicate that no sort bin has been +specified. + +=back + +=head2 C<($status, $screen_msg, $print_line) = $ils-Eend_patron_session($patron_id)> + +This function informs the ILS that the current patron's session +has ended. This allows the ILS to free up any internal state +that it may be preserving between messages from the self check +unit. The function returns a boolean C<$status>, where C +indicates success, and two strings: a screen message to display +on the self check unit's console, and a print line to be printed +on the unit's receipt printer. + +=head2 C<$status = $ils-Epay_fee($patron_id, $patron_pwd, $fee_amt, $fee_type, $pay_type, $fee_id, $trans_id, $currency)> + +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: + +=over + +=item C<$fee_amt> + +The amount of the fee. + +=item C<$fee_type> + +The type of fee, according a table in the SIP protocol +specification. + +=item C<$pay_type> + +The payment method. Defined in the SIP protocol specification. + +=item C<$fee_id> + +Optional. Identifies which particular fee was paid. This +identifier would have been sent from the ILS to the Self Check +unit by a previous "Patron Information Response" message. + +=item C<$trans_id> + +Optional. A transaction identifier set by the payment device. +This should be recorded by the ILS for financial tracking +purposes. + +=item C<$currency> + +An ISO currency code indicating the currency in which the fee was +paid. + +=back + +The status object returned by the C must support the +following methods: + +=over + +=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. + +=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: + +=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. + +=item C + +Missing POD for new. + +=item C + +Missing POD for find_patron. + +=item C + +Missing POD for institution. + +=item C + +Missing POD for institution_id. + +=item C + +Missing POD for supports. + +=item C + +Missing POD for check_inst_id. + +=item C + +Missing POD for find_item. + +=item C + +Missing POD for test_cardnumber_compare. + +=item C + +Missing POD for to_bool. + +=back diff --git a/C4/SIP/ILS.pod b/C4/SIP/ILS.pod deleted file mode 100644 index eeb8ee20dac..00000000000 --- a/C4/SIP/ILS.pod +++ /dev/null @@ -1,485 +0,0 @@ -=head1 NAME - -ILS - Portability layer to interface between Open-SIP and ILS - -=head1 SYNOPSIS - - use ILS; - - # Initialize connection between SIP and the ILS - my $ils = new ILS (institution => 'Foo Public Library'); - - # Basic object access methods - $inst_name = $self->institution; - $bool = $self->support($operation); - $self->check_inst_id($inst_name, "error message"); - - # 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->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 -server and the rest of the integrated library system. It is the -responsibility of the ILS vendor to implement the functions -defined by this interface. This allows the SIP server to be -reasonably portable between ILS systems (of course, we won't know -exactly I portable the interface is until it's been used by -a second ILS. - -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. 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 - -The first thing the SIP server does, after a terminal has -successfully logged in, is initialize the ILS module by calling - - $ils = new ILS $institution - -where C<$institution> is a hash ( institution => 'Foo Public Library' ) -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 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 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 -the patron with barcode C<$patron_id>. If C<$sc_renew> is true, -then the self-check terminal has been configured to allow -self-renewal of items, and the ILS may take this into account -when deciding how to handle the case where C<$item_id> is already -checked out to C<$patron_id>. - -The C<$status> object returned by C must support the -following methods: - -=over - -=item C - -Is this transaction actually a renewal? That is, did C<$patron_id> -already have C<$item_id> checked out? - -=item C - -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 - -Should self checkout unit ignore the security status of this -item? - -This method will only be used if - - $ils->supports('security inhibit') - -returns 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. - -=item C - -The ISO currency code for the currency in which the fee -associated with this item is denominated. For example, 'USD' or -'CAD'. - -=item C - -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 - -=head2 C<$status = $ils-Echeckin($item_id, $trans_date, $return_date, $current_loc, $item_props, $cancel)> - -Check in item identified by barcode C<$item_id>. This -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>. 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 - -Does the item need to be resensitized by 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 - -Certain self checkin units provide for automated sorting of the -returned items. This function returns the bin number into which -the received item should be placed. This function may return the -empty string, or C, to indicate that no sort bin has been -specified. - -=back - -=head2 C<($status, $screen_msg, $print_line) = $ils-Eend_patron_session($patron_id)> - -This function informs the ILS that the current patron's session -has ended. This allows the ILS to free up any internal state -that it may be preserving between messages from the self check -unit. The function returns a boolean C<$status>, where C -indicates success, and two strings: a screen message to display -on the self check unit's console, and a print line to be printed -on the unit's receipt printer. - -=head2 C<$status = $ils-Epay_fee($patron_id, $patron_pwd, $fee_amt, $fee_type, $pay_type, $fee_id, $trans_id, $currency)> - -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: - -=over - -=item C<$fee_amt> - -The amount of the fee. - -=item C<$fee_type> - -The type of fee, according a table in the SIP protocol -specification. - -=item C<$pay_type> - -The payment method. Defined in the SIP protocol specification. - -=item C<$fee_id> - -Optional. Identifies which particular fee was paid. This -identifier would have been sent from the ILS to the Self Check -unit by a previous "Patron Information Response" message. - -=item C<$trans_id> - -Optional. A transaction identifier set by the payment device. -This should be recorded by the ILS for financial tracking -purposes. - -=item C<$currency> - -An ISO currency code indicating the currency in which the fee was -paid. - -=back - -The status object returned by the C must support the -following methods: - -=over - -=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. - -=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: - -=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 diff --git a/C4/SIP/ILS/Item.pm b/C4/SIP/ILS/Item.pm index a340f1e592d..5756ba6b0c7 100644 --- a/C4/SIP/ILS/Item.pm +++ b/C4/SIP/ILS/Item.pm @@ -586,5 +586,236 @@ sub format { } 1; -__END__ +=head1 NAME + +ILS::Item - Portable Item status object class for SIP + +=head1 SYNOPSIS + + use ILS; + use ILS::Item; + + # Look up item based on item_id + my $item = new ILS::Item $item_id; + + # Basic object access methods + $item_id = $item->id; + $title = $item->title_id; + $media_type = $item->sip_media_type; + $bool = $item->magnetic_media; + $locn = $item->permanent_location; + $locn = $item->current_location; + $props = $item->sip_item_props; + $owner = $item->owner; + $str = $item->sip_circulation_status; + $bool = $item->available; + @hold_queue = $item->hold_queue; + $pos = $item->hold_queue_position($patron_id); + $due = $item->due_date; + $pickup = $item->hold_pickup_date; + $recall = $item->recall_date; + $fee = $item->fee; + $currency = $item->fee_currency; + $type = $item->sip_fee_type; + $mark = $item->sip_security_marker; + $msg = $item->screen_msg; + $msg = $item->print_line; + + # Operations on items + $status = $item->status_update($item_props); + +=head1 DESCRIPTION + +An C object holds the information necessary to +circulate an item in the library's collection. It does not need +to be a complete bibliographic description of the item; merely +basic human-appropriate identifying information is necessary +(that is, not the barcode, but just a title, and maybe author). + +For the most part, Cs are not operated on directly, +but are passed to C methods as part of a transaction. That +is, rather than having an item check itself in: + + $item->checkin; + +the code tells the ILS that the item has returned: + + $ils->checkin($item_id); + +Similarly, patron's don't check things out (a la, +C<$patron-Echeckout($item)>), but the ILS checks items out to +patrons. This means that the methods that are defined for items +are, almost exclusively, methods to retrieve information about +the state of the item. + +=over + +=item C<$item_id = $item-Eid> + +Return the item ID, or barcode, of C<$item>. + +=item C<$title = $item-Etitle_id> + +Return the title, or some other human-relevant description, of +the item. + +=item C<$media_type = $item-Emedia_type> + +Return the SIP-defined media type of the item. The specification +provides the following definitions: + + 000 Other + 001 Book + 002 Magazine + 003 Bound journal + 004 Audio tape + 005 Video tape + 006 CD/CDROM + 007 Diskette + 008 Book with diskette + 009 Book with CD + 010 Book with audio tape + +The SIP server does not use the media type code to alter its +behavior at all; it merely passes it through to the self-service +terminal. In particular, it does not set indicators related to +whether an item is magnetic, or whether it should be +desensitized, based on this return type. The +C<$item-Emagnetic_media> method will be used for that purpose. + +=item C + +Is the item some form of magnetic media (eg, a video or a book +with an accompanying floppy)? This method will not be called +unless + + $ils->supports('magnetic media') + +returns C. + +If this method is defined, it is assumed to return either C +or C for every item. If the magnetic media indication is +not supported by the ILS, then the SIP server will indicate that +all items are 'Unknown'. + +=item C<$locn = $item-Epermanent_location> + +Where does this item normally reside? The protocol specification +is not clear on whether this is the item's "home branch", or a +location code within the branch, merely stating that it is, "The +location where an item is normally stored after being checked +in." + +=item C<$locn = $item-Ecurrent_location> + +According to the protocol, "[T]he current location of the item. +[A checkin terminal] could set this field to the ... system +terminal location on a Checkin message." + +=item C<$props = $item-Esip_item_props> + +Returns "item properties" associated with the item. This is an +(optional) opaque string that is passed between the self-service +terminals and the ILS. It can be set by the terminal, and should +be stored in the ILS if it is. + +=item C<$owner = $item-Eowner> + +The spec says, "This field might contain the name of the +institution or library that owns the item." + +=item C<$str = $item-Esip_circulation_status> + +Returns a two-character string describing the circulation status +of the item, as defined in the specification: + + 01 Other + 02 On order + 03 Available + 04 Charged + 05 Charged; not to be recalled until earliest recall date + 06 In process + 07 Recalled + 08 Waiting on hold shelf + 09 Waiting to be re-shelved + 10 In transit between library locations + 11 Claimed returned + 12 Lost + 13 Missing + +=item C<$bool = $item-Eavailable> + +Is the item available? That is, not checked out, and not on the +hold shelf? + +=item C<@hold_queue = $item-Ehold_queue> + +Returns a list of the C<$patron_id>s of the patrons that have +outstanding holds on the item. + +=item C<$pos = $item-Ehold_queue_position($patron_id)> + +Returns the location of C<$patron_id> in the hold queue for the +item, with '1' indicating the next person to receive the item. A +return status of '0' indicates that C<$patron_id> does not have a +hold on the item. + +=item C<$date = $item-Erecall_date> +=item C<$date = $item-Ehold_pickup_date> + +These functions all return the corresponding date as a standard +SIP-format timestamp: + + YYYYMMDDZZZZHHMMSS + +Where the C<'Z'> characters indicate spaces. + +=item C<$date = $item-Edue_date> + +Returns the date the item is due. The format for this timestamp +is not defined by the specification, but it should be something +simple for a human reader to understand. + +=item C<$fee = $item-Efee> + +The amount of the fee associated with borrowing this item. + +=item C<$currency = $item-Efee_currency> + +The currency in which the fee type above is denominated. This +field is the ISO standard 4217 three-character currency code. It +is highly unlikely that many systems will denominate fees in more +than one currency, however. + +=item C<$type = $item-Esip_fee_type> + +The type of fee being charged, as defined by the SIP protocol +specification: + + 01 Other/unknown + 02 Administrative + 03 Damage + 04 Overdue + 05 Processing + 06 Rental + 07 Replacement + 08 Computer access charge + 09 Hold fee + +=item C<$mark = $item-Esip_security_marker> + +The type of security system with which the item is tagged: + + 00 Other + 01 None + 02 3M Tattle-tape + 03 3M Whisper tape + +=item C<$msg = $item-Escreen_msg> + +=item C<$msg = $item-Eprint_line> + +The usual suspects. + +=back diff --git a/C4/SIP/ILS/Item.pod b/C4/SIP/ILS/Item.pod deleted file mode 100644 index 29f6761317f..00000000000 --- a/C4/SIP/ILS/Item.pod +++ /dev/null @@ -1,232 +0,0 @@ -=head1 NAME - -ILS::Item - Portable Item status object class for SIP - -=head1 SYNOPSIS - - use ILS; - use ILS::Item; - - # Look up item based on item_id - my $item = new ILS::Item $item_id; - - # Basic object access methods - $item_id = $item->id; - $title = $item->title_id; - $media_type = $item->sip_media_type; - $bool = $item->magnetic_media; - $locn = $item->permanent_location; - $locn = $item->current_location; - $props = $item->sip_item_props; - $owner = $item->owner; - $str = $item->sip_circulation_status; - $bool = $item->available; - @hold_queue = $item->hold_queue; - $pos = $item->hold_queue_position($patron_id); - $due = $item->due_date; - $pickup = $item->hold_pickup_date; - $recall = $item->recall_date; - $fee = $item->fee; - $currency = $item->fee_currency; - $type = $item->sip_fee_type; - $mark = $item->sip_security_marker; - $msg = $item->screen_msg; - $msg = $item->print_line; - - # Operations on items - $status = $item->status_update($item_props); - -=head1 DESCRIPTION - -An C object holds the information necessary to -circulate an item in the library's collection. It does not need -to be a complete bibliographic description of the item; merely -basic human-appropriate identifying information is necessary -(that is, not the barcode, but just a title, and maybe author). - -For the most part, Cs are not operated on directly, -but are passed to C methods as part of a transaction. That -is, rather than having an item check itself in: - - $item->checkin; - -the code tells the ILS that the item has returned: - - $ils->checkin($item_id); - -Similarly, patron's don't check things out (a la, -C<$patron-Echeckout($item)>), but the ILS checks items out to -patrons. This means that the methods that are defined for items -are, almost exclusively, methods to retrieve information about -the state of the item. - -=over - -=item C<$item_id = $item-Eid> - -Return the item ID, or barcode, of C<$item>. - -=item C<$title = $item-Etitle_id> - -Return the title, or some other human-relevant description, of -the item. - -=item C<$media_type = $item-Emedia_type> - -Return the SIP-defined media type of the item. The specification -provides the following definitions: - - 000 Other - 001 Book - 002 Magazine - 003 Bound journal - 004 Audio tape - 005 Video tape - 006 CD/CDROM - 007 Diskette - 008 Book with diskette - 009 Book with CD - 010 Book with audio tape - -The SIP server does not use the media type code to alter its -behavior at all; it merely passes it through to the self-service -terminal. In particular, it does not set indicators related to -whether an item is magnetic, or whether it should be -desensitized, based on this return type. The -C<$item-Emagnetic_media> method will be used for that purpose. - -=item C - -Is the item some form of magnetic media (eg, a video or a book -with an accompanying floppy)? This method will not be called -unless - - $ils->supports('magnetic media') - -returns C. - -If this method is defined, it is assumed to return either C -or C for every item. If the magnetic media indication is -not supported by the ILS, then the SIP server will indicate that -all items are 'Unknown'. - -=item C<$locn = $item-Epermanent_location> - -Where does this item normally reside? The protocol specification -is not clear on whether this is the item's "home branch", or a -location code within the branch, merely stating that it is, "The -location where an item is normally stored after being checked -in." - -=item C<$locn = $item-Ecurrent_location> - -According to the protocol, "[T]he current location of the item. -[A checkin terminal] could set this field to the ... system -terminal location on a Checkin message." - -=item C<$props = $item-Esip_item_props> - -Returns "item properties" associated with the item. This is an -(optional) opaque string that is passed between the self-service -terminals and the ILS. It can be set by the terminal, and should -be stored in the ILS if it is. - -=item C<$owner = $item-Eowner> - -The spec says, "This field might contain the name of the -institution or library that owns the item." - -=item C<$str = $item-Esip_circulation_status> - -Returns a two-character string describing the circulation status -of the item, as defined in the specification: - - 01 Other - 02 On order - 03 Available - 04 Charged - 05 Charged; not to be recalled until earliest recall date - 06 In process - 07 Recalled - 08 Waiting on hold shelf - 09 Waiting to be re-shelved - 10 In transit between library locations - 11 Claimed returned - 12 Lost - 13 Missing - -=item C<$bool = $item-Eavailable> - -Is the item available? That is, not checked out, and not on the -hold shelf? - -=item C<@hold_queue = $item-Ehold_queue> - -Returns a list of the C<$patron_id>s of the patrons that have -outstanding holds on the item. - -=item C<$pos = $item-Ehold_queue_position($patron_id)> - -Returns the location of C<$patron_id> in the hold queue for the -item, with '1' indicating the next person to receive the item. A -return status of '0' indicates that C<$patron_id> does not have a -hold on the item. - -=item C<$date = $item-Erecall_date> -=item C<$date = $item-Ehold_pickup_date> - -These functions all return the corresponding date as a standard -SIP-format timestamp: - - YYYYMMDDZZZZHHMMSS - -Where the C<'Z'> characters indicate spaces. - -=item C<$date = $item-Edue_date> - -Returns the date the item is due. The format for this timestamp -is not defined by the specification, but it should be something -simple for a human reader to understand. - -=item C<$fee = $item-Efee> - -The amount of the fee associated with borrowing this item. - -=item C<$currency = $item-Efee_currency> - -The currency in which the fee type above is denominated. This -field is the ISO standard 4217 three-character currency code. It -is highly unlikely that many systems will denominate fees in more -than one currency, however. - -=item C<$type = $item-Esip_fee_type> - -The type of fee being charged, as defined by the SIP protocol -specification: - - 01 Other/unknown - 02 Administrative - 03 Damage - 04 Overdue - 05 Processing - 06 Rental - 07 Replacement - 08 Computer access charge - 09 Hold fee - -=item C<$mark = $item-Esip_security_marker> - -The type of security system with which the item is tagged: - - 00 Other - 01 None - 02 3M Tattle-tape - 03 3M Whisper tape - -=item C<$msg = $item-Escreen_msg> - -=item C<$msg = $item-Eprint_line> - -The usual suspects. - -=back diff --git a/C4/SIP/ILS/Patron.pm b/C4/SIP/ILS/Patron.pm index d7361083a2e..6c90b330bc0 100644 --- a/C4/SIP/ILS/Patron.pm +++ b/C4/SIP/ILS/Patron.pm @@ -923,3 +923,215 @@ __END__ {itemlist} ref-to-array: list of available items =cut + + +=head1 NAME + +ILS::Patron - Portable Patron status object class for SIP + +=head1 DESCRIPTION + +A C object holds information about a patron that's +used by self service terminals to authenticate and authorize a patron, +and to display information about the patron's borrowing activity. + +=head1 SYNOPSIS + + use ILS; + use ILS::Patron; + + # Look up patron based on patron_id + my $patron = new ILS::Patron $patron_id + + # Basic object access methods + $patron_id = $patron->id; + $str = $patron->name; + $str = $patron->address; + $str = $patron->email_addr; + $str = $patron->home_phone; + $str = $patron->sip_birthdate; + $str = $patron->ptype; + $str = $patron->language; + $str = $patron->password; + $str = $patron->check_password($password); + $str = $patron->currency; + $str = $patron->screen_msg; + $str = $patron->print_line; + + # Check patron permissions + $bool = $patron->charge_ok; + $bool = $patron->renew_ok; + $bool = $patron->recall_ok; + $bool = $patron->hold_ok; + $bool = $patron->card_lost; + $bool = $patron->too_many_charged; + $bool = $patron->too_many_overdue; + $bool = $patron->too_many_renewal; + $bool = $patron->too_many_claim_return; + $bool = $patron->too_many_lost( $server ); + $bool = $patron->excessive_fines; + $bool = $patron->excessive_fees; + $bool = $patron->too_many_billed; + + # Patron borrowing activity + $num = $patron->recall_overdue; + $num = $patron->fee_amount; + $bool = $patron->drop_hold($item_id); + @holds = $patron->hold_items($start, $end); + @items = $patron->overdue_items($start, $end); + @items = $patron->charged_items($start, $end); + @items = $patron->fine_items($start, $end); + @items = $patron->recall_items($start, $end); + @items = $patron->unavail_holds($start, $end); + + # Changing a patron's status + $patron->block($card_retained, $blocked_msg); + $patron->enable; + +=head1 INITIALIZATION + +A patron object is created by calling + + $patron = new ILS::Patron $patron_id; + +where C<$patron_id> is the patron's barcode as received from the +self service terminal. If the patron barcode is not registered, +then C should return C. + +=head1 BASIC OBJECT ACCESS METHODS + +The following functions return the corresponding information +about the given patron, or C if the information is +unavailable. + + $patron_id = $patron-Eid; + $str = $patron-Ename; + $str = $patron-Eaddress; + $str = $patron-Eemail_addr; + $str = $patron-Ehome_phone; + + $str = $patron-Escreen_msg; + $str = $patron-Eprint_line; + +If there are outstanding display messages associated with the +patron, then these return the screen message and print line, +respectively, as with the C methods. + +There are a few other object access methods that need a bit more +explication however. + +=head2 C<$str = $patron-Esip_birthdate;> + +Returns the patron's birthday formatted according to the SIP +specification: + + YYYYMMDD HHMMSS + +=head2 C<$str = $patron-Eptype;> + +Returns the "patron type" of the patron. This is not used by the +SIP server code, but is passed through to the self service +terminal (using the non-standard protocol field "PC"). Some self +service terminals use the patron type in determining what level +of service to provide (for example, Envisionware computer +management software can be configured to filter internet access +based on patron type). + +=head2 C<$str = $patron-Elanguage;> + +A three-digit string encoding the patron's preferred language. +The full list is defined in the SIP specification, but some of +the important values are: + + 000 Unknown (default) + 001 English + 002 French + 008 Spanish + 011 Canadian French + 016 Arabic + 019 Chinese + 021 North American Spanish + +=head2 C<$bool = $patron-Echeck_password($password);> + +Returns C if C<$patron>'s password is C<$password>. + +=head2 C<$str = $patron-Ecurrency;> + +Returns the three character ISO 4217 currency code for the +patron's preferred currency. + +=head1 CHECKING PATRON PERMISSIONS + +Most of the methods associated with Patrons are related to +checking if they're authorized to perform various actions: + + $bool = $patron-Echarge_ok; + $bool = $patron-Erenew_ok; + $bool = $patron-Erecall_ok; + $bool = $patron-Ehold_ok; + $bool = $patron-Ecard_lost; + $bool = $patron-Erecall_overdue; + $bool = $patron-Etoo_many_charged; + $bool = $patron-Etoo_many_overdue; + $bool = $patron-Etoo_many_renewal; + $bool = $patron-Etoo_many_claim_return; + $bool = $patron-Etoo_many_lost( $server ); + $bool = $patron-Eexcessive_fines; + $bool = $patron-Eexcessive_fees; + $bool = $patron-Etoo_many_billed; + +=head1 LISTS OF ITEMS ASSOCIATED WITH THE USER + +The C<$patron> object provides a set of methods to find out +information about various sets that are associated with the +user. All these methods take two optional parameters: C<$start> +and C<$end>, which define a subset of the list of items to be +returned (C<1> is the first item in the list). The following +methods all return a reference to a list of C<$item_id>s: + + $items = $patron-Ehold_items($start, $end); + $items = $patron-Eoverdue_items($start, $end); + $items = $patron-Echarged_items($start, $end); + $items = $patron-Erecall_items($start, $end); + $items = $patron-Eunavail_holds($start, $end); + +It is also possible to retrieve an itemized list of the fines +outstanding. This method returns a reference to an itemized list +of fines: + + $fines = $patron-Efine_items($start, $end); + +=head1 PATRON BORROWING ACTIVITY + +=head2 C<$num = $patron-Efee_amount;> + +The total amount of fees and fines owed by the patron. + +=head2 C<$bool = $patron-Edrop_hold($item_id);> + +Drops the hold that C<$patron> has placed on the item +C<$item_id>. Returns C if the patron did not have a hold +on the item, C otherwise. + + + +=head1 CHANGING A PATRON'S STATUS + +=head2 C<$status = $ils-Eblock($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<$patron-Eenable;> + +Reenable the patron after she's been blocked. This is a test +function and will not normally be called by self-service +terminals in production. diff --git a/C4/SIP/ILS/Patron.pod b/C4/SIP/ILS/Patron.pod deleted file mode 100644 index 80061b0172f..00000000000 --- a/C4/SIP/ILS/Patron.pod +++ /dev/null @@ -1,210 +0,0 @@ -=head1 NAME - -ILS::Patron - Portable Patron status object class for SIP - -=head1 DESCRIPTION - -A C object holds information about a patron that's -used by self service terminals to authenticate and authorize a patron, -and to display information about the patron's borrowing activity. - -=head1 SYNOPSIS - - use ILS; - use ILS::Patron; - - # Look up patron based on patron_id - my $patron = new ILS::Patron $patron_id - - # Basic object access methods - $patron_id = $patron->id; - $str = $patron->name; - $str = $patron->address; - $str = $patron->email_addr; - $str = $patron->home_phone; - $str = $patron->sip_birthdate; - $str = $patron->ptype; - $str = $patron->language; - $str = $patron->password; - $str = $patron->check_password($password); - $str = $patron->currency; - $str = $patron->screen_msg; - $str = $patron->print_line; - - # Check patron permissions - $bool = $patron->charge_ok; - $bool = $patron->renew_ok; - $bool = $patron->recall_ok; - $bool = $patron->hold_ok; - $bool = $patron->card_lost; - $bool = $patron->too_many_charged; - $bool = $patron->too_many_overdue; - $bool = $patron->too_many_renewal; - $bool = $patron->too_many_claim_return; - $bool = $patron->too_many_lost( $server ); - $bool = $patron->excessive_fines; - $bool = $patron->excessive_fees; - $bool = $patron->too_many_billed; - - # Patron borrowing activity - $num = $patron->recall_overdue; - $num = $patron->fee_amount; - $bool = $patron->drop_hold($item_id); - @holds = $patron->hold_items($start, $end); - @items = $patron->overdue_items($start, $end); - @items = $patron->charged_items($start, $end); - @items = $patron->fine_items($start, $end); - @items = $patron->recall_items($start, $end); - @items = $patron->unavail_holds($start, $end); - - # Changing a patron's status - $patron->block($card_retained, $blocked_msg); - $patron->enable; - -=head1 INITIALIZATION - -A patron object is created by calling - - $patron = new ILS::Patron $patron_id; - -where C<$patron_id> is the patron's barcode as received from the -self service terminal. If the patron barcode is not registered, -then C should return C. - -=head1 BASIC OBJECT ACCESS METHODS - -The following functions return the corresponding information -about the given patron, or C if the information is -unavailable. - - $patron_id = $patron-Eid; - $str = $patron-Ename; - $str = $patron-Eaddress; - $str = $patron-Eemail_addr; - $str = $patron-Ehome_phone; - - $str = $patron-Escreen_msg; - $str = $patron-Eprint_line; - -If there are outstanding display messages associated with the -patron, then these return the screen message and print line, -respectively, as with the C methods. - -There are a few other object access methods that need a bit more -explication however. - -=head2 C<$str = $patron-Esip_birthdate;> - -Returns the patron's birthday formatted according to the SIP -specification: - - YYYYMMDD HHMMSS - -=head2 C<$str = $patron-Eptype;> - -Returns the "patron type" of the patron. This is not used by the -SIP server code, but is passed through to the self service -terminal (using the non-standard protocol field "PC"). Some self -service terminals use the patron type in determining what level -of service to provide (for example, Envisionware computer -management software can be configured to filter internet access -based on patron type). - -=head2 C<$str = $patron-Elanguage;> - -A three-digit string encoding the patron's preferred language. -The full list is defined in the SIP specification, but some of -the important values are: - - 000 Unknown (default) - 001 English - 002 French - 008 Spanish - 011 Canadian French - 016 Arabic - 019 Chinese - 021 North American Spanish - -=head2 C<$bool = $patron-Echeck_password($password);> - -Returns C if C<$patron>'s password is C<$password>. - -=head2 C<$str = $patron-Ecurrency;> - -Returns the three character ISO 4217 currency code for the -patron's preferred currency. - -=head1 CHECKING PATRON PERMISSIONS - -Most of the methods associated with Patrons are related to -checking if they're authorized to perform various actions: - - $bool = $patron-Echarge_ok; - $bool = $patron-Erenew_ok; - $bool = $patron-Erecall_ok; - $bool = $patron-Ehold_ok; - $bool = $patron-Ecard_lost; - $bool = $patron-Erecall_overdue; - $bool = $patron-Etoo_many_charged; - $bool = $patron-Etoo_many_overdue; - $bool = $patron-Etoo_many_renewal; - $bool = $patron-Etoo_many_claim_return; - $bool = $patron-Etoo_many_lost( $server ); - $bool = $patron-Eexcessive_fines; - $bool = $patron-Eexcessive_fees; - $bool = $patron-Etoo_many_billed; - -=head1 LISTS OF ITEMS ASSOCIATED WITH THE USER - -The C<$patron> object provides a set of methods to find out -information about various sets that are associated with the -user. All these methods take two optional parameters: C<$start> -and C<$end>, which define a subset of the list of items to be -returned (C<1> is the first item in the list). The following -methods all return a reference to a list of C<$item_id>s: - - $items = $patron-Ehold_items($start, $end); - $items = $patron-Eoverdue_items($start, $end); - $items = $patron-Echarged_items($start, $end); - $items = $patron-Erecall_items($start, $end); - $items = $patron-Eunavail_holds($start, $end); - -It is also possible to retrieve an itemized list of the fines -outstanding. This method returns a reference to an itemized list -of fines: - - $fines = $patron-Efine_items($start, $end); - -=head1 PATRON BORROWING ACTIVITY - -=head2 C<$num = $patron-Efee_amount;> - -The total amount of fees and fines owed by the patron. - -=head2 C<$bool = $patron-Edrop_hold($item_id);> - -Drops the hold that C<$patron> has placed on the item -C<$item_id>. Returns C if the patron did not have a hold -on the item, C otherwise. - - - -=head1 CHANGING A PATRON'S STATUS - -=head2 C<$status = $ils-Eblock($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<$patron-Eenable;> - -Reenable the patron after she's been blocked. This is a test -function and will not normally be called by self-service -terminals in production. diff --git a/C4/SIP/Sip.pm b/C4/SIP/Sip.pm index fbd4c26a3a6..c1450c8dff6 100644 --- a/C4/SIP/Sip.pm +++ b/C4/SIP/Sip.pm @@ -48,6 +48,12 @@ our $field_delimiter = '|'; # Protocol Default our $last_response = ''; +=head2 y_or_n + +Missing POD for y_or_n. + +=cut + =head2 timestamp Missing POD for timestamp. -- 2.34.1