NAME

ILS - Portability layer to interface between Open-SIP and ILS

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);

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 how 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, ILS::Patron and ILS::Item. 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 ILS::Patron and ILS::Item for the details.

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 $institution is an object of type Sip::Configuration::Institution, 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 $institution of the terminal.

BASIC OBJECT ACCESS AND PROTOCOL SUPPORT

The $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.

`$inst_name = $self->institution;`

Returns the institution ID as a string, suitable for incorporating into a SIP response message.

`$bool = $self->support($operation);`

Reports whether this ILS implementation supports certain operations that are necessary to report information to the SIP terminal. The argument $operation is a string from this list:

'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?
'security inhibit': Is the ILS capable of directing the terminal to ignore the security status of an item?
'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?

`$bool = $self->checkout_ok;`

Are the self service terminals permitted to check items out to patrons?

`$bool = $self->checkin_ok;`

Are the self service terminals permitted to check items in?

`$bool = $self->status_update_ok;`

Are the self service terminals permitted to update patron status information. For example, can terminals block patrons?

`$bool = $self->offline_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?

THE TRANSACTIONS

In general, every protocol transaction that changes the status of some ILS object (Patron or Item) has a corresponding ILS method. Operations like Check In, which are a function of both a patron and an item are ILS functions, while others, like Patron Status or Item Status, 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 $status objects returned by the various ILS transactions are objects that are subclasses of a virtual ILS::Transaction object, but this is not required of the SIP code, as long as the status objects support the appropriate methods.

CORE TRANSACTION STATUS METHODS

The $status objects returned by all transactions must support the following common methods:

ok: Returns true if the transaction was successful and false if not. Other methods can be used to find out what went wrong.
item: Returns an ILS::Item object corresponding to the item with the barcode $item_id, or undef if the barcode is invalid.
patron: Returns a ILS::Patron object corresponding to the patron with the barcode $patron_id, or undef if the barcode is invalid (ie, nonexistent, as opposed to "expired" or "delinquent").
screen_msg: 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.
print_line: 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).

`$status = $ils->checkout($patron_id, $item_id, $sc_renew)`

Check out (or possibly renew) item with barcode $item_id to the patron with barcode $patron_id. If $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 $item_id is already checked out to $patron_id.

The $status object returned by checkout must support the following methods:

renewal_ok

Is this transaction actually a renewal? That is, did $patron_id already have $item_id checked out?

desensitize

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.

security_inhibit

Should self checkout unit ignore the security status of this item?

This method will only be used if

    $ils->supports('security inhibit')

returns true.

fee_amount

If there is a fee associated with the use of $item_id, then this method should return the amount of the fee, otherwise it should return zero. See also the sip_currency and sip_fee_type methods.

sip_currency

The ISO currency code for the currency in which the fee associated with this item is denominated. For example, 'USD' or 'CAD'.

sip_fee_type

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.

`$status = $ils->checkin($item_id, $trans_date, $return_date, $current_loc, $item_props, $cancel)`

Check in item identified by barcode $item_id. This transaction took place at time $trans_date and was effective $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 $current_loc, and the item has properties $item_props. The parameters $current_loc and $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 $status object returned by the checkin operation must support the following methods:

resensitize: Does the item need to be resensitized by the self check unit?
alert: Should the self check unit generate an audible alert to notify staff that the item has been returned?
sort_bin: 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 undef, to indicate that no sort bin has been specified.

`($status, $screen_msg, $print_line) = $ils->end_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 $status, where true 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.

`$status = $ils->pay_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 $patron_id (who has password $patron_pwd, which is an optional parameter). The other parameters are:

$fee_amt: The amount of the fee.
$fee_type: The type of fee, according a table in the SIP protocol specification.
$pay_type: The payment method. Defined in the SIP protocol specification.
$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.
$trans_id: Optional. A transaction identifier set by the payment device. This should be recorded by the ILS for financial tracking purposes.
$currency: An ISO currency code indicating the currency in which the fee was paid.

The status object returned by the pay_fee must support the following methods:

transaction_id: Transaction identifier of the transaction. This parallels the optional $trans_id sent from the terminal to the ILS. This may return an empty string.

`$status = $ils->add_hold($patron_id, $patron_pwd, $item_id, $title_id, $expiry_date, $pickup_locn, $hold_type, $fee_ack);`

Places a hold for $patron_id (optionally, with password $patron_pwd) on the item described by either $item_id or $title_id. The other parameters are:

$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.

$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.

$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.

$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 $fee_ack is false, then the ILS should refuse to place the hold.

`$status = $ils->cancel_hold($patron_id, $patron_pwd, $item_id, $title_id);`

Cancel a hold placed by $patron_id for the item identified by $item_id or $title_id. The patron password $patron_pwd may be undef, if it was not provided by the terminal.

`$status = $ils->alter_hold($patron_id, $patron_pwd, $item_id, $title_id, $expiry_date, $pickup_locn, $hold_type, $fee_ack);`

The $status object returned by $ils->add_hold, $ils->cancel_hold, and $ils->alter_hold must all support the same methods:

expiration_date: Returns the expiry date for the placed hold, in seconds since the epoch.
queue_position: Returns the new hold's place in the queue of outstanding holds.
pickup_location: Returns the location code for the pickup location.

`$status = $ils->renew($patron_id, $patron_pwd, $item_id, $title_id, $no_block, $nb_due_date, $third_party, $item_props, $fee_ack);`

Renew the item identified by $item_id or $title_id, as requested by $patron_id (with password $patron_pwd). The item has the properties $item_props associated with it.

If the patron renewed the item while the terminal was disconnected from the net, then it is a $no_block transaction, and the due date assigned by the terminal, and reported to the patron was $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 $fee_ack will be 'Y'.

If $third_party is 'Y' and the book is not checked out to $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 $patron_id, or the renewal should fail.

The $status object returned by $ils->renew must support the following methods:

renewal_ok

Boolean. If renewal_ok is true, then the item was already checked out to the patron, so it is being renewed. If renewal_ok is false, then the patron did not already have the item checked out.

NOTE: HOW IS THIS USED IN PRACTICE?

desensitize, security_inhibit, fee_amount, sip_currency, sip_fee_type, transaction_id

See $ils->checkout for these methods.

`$status = $ils->renew_all($patron_id, $patron_pwd, $fee_ack);`

Renew all items checked out by $patron_id (with password $patron_pwd). If the patron has agreed to pay any fees associated with this transaction, then $fee_ack will be 'Y'.

The $status object must support the following methods:

renewed: Returns a list of the $item_ids of the items that were renewed.
unrenewed: Returns a list of the $item_ids of the items that were not renewed.