ILS::Item - Portable Item status object class for SIP


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


An ILS::Item 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, ILS::Items are not operated on directly, but are passed to ILS methods as part of a transaction. That is, rather than having an item check itself in:


the code tells the ILS that the item has returned:


Similarly, patron's don't check things out (a la, $patron->checkout($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.

$item_id = $item->id

Return the item ID, or barcode, of $item.

$title = $item->title_id

Return the title, or some other human-relevant description, of the item.

$media_type = $item->media_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 $item->magnetic method will be used for that purpose.


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

If this method is defined, it is assumed to return either true or false 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'.

$locn = $item->permanent_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."

$locn = $item->current_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."

$props = $item->sip_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.

$owner = $item->owner

The spec says, "This field might contain the name of the institution or library that owns the item."

$str = $item->sip_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
$bool = $item->available

Is the item available? That is, not checked out, and not on the hold shelf?

@hold_queue = $item->hold_queue

Returns a list of the $patron_ids of the patrons that have outstanding holds on the item.

$pos = $item->hold_queue_position($patron_id)

Returns the location of $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 $patron_id does not have a hold on the item.

$date = $item->recall_date =item $date = $item->hold_pickup_date

These functions all return the corresponding date as a standard SIP-format timestamp:


Where the 'Z' characters indicate spaces.

$date = $item->due_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.

$fee = $item->fee

The amount of the fee associated with borrowing this item.

$currency = $item->fee_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.

$type = $item->sip_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
$mark = $item->sip_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
$msg = $item->screen_msg
$msg = $item->print_line

The usual suspects.