Koha/C4/SIP/ILS/Item.pod
Joe Atzberger 08816bab07 bug 3435: SIP Checkin extension for 3M SmartChute - partial
Signed-off-by: Galen Charlton <galen.charlton@liblime.com>
2009-07-30 11:06:47 -04:00

232 lines
6.4 KiB
Text

=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<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, C<ILS::Item>s are not operated on directly,
but are passed to C<ILS> 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-E<gt>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.
=over
=item C<$item_id = $item-E<gt>id>
Return the item ID, or barcode, of C<$item>.
=item C<$title = $item-E<gt>title_id>
Return the title, or some other human-relevant description, of
the item.
=item C<$media_type = $item-E<gt>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
C<$item-E<gt>magnetic_media> method will be used for that purpose.
=item C<magnetic_media>
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<true>.
If this method is defined, it is assumed to return either C<true>
or C<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'.
=item C<$locn = $item-E<gt>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."
=item C<$locn = $item-E<gt>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."
=item C<$props = $item-E<gt>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.
=item C<$owner = $item-E<gt>owner>
The spec says, "This field might contain the name of the
institution or library that owns the item."
=item C<$str = $item-E<gt>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
=item C<$bool = $item-E<gt>available>
Is the item available? That is, not checked out, and not on the
hold shelf?
=item C<@hold_queue = $item-E<gt>hold_queue>
Returns a list of the C<$patron_id>s of the patrons that have
outstanding holds on the item.
=item C<$pos = $item-E<gt>hold_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-E<gt>recall_date>
=item C<$date = $item-E<gt>hold_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-E<gt>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.
=item C<$fee = $item-E<gt>fee>
The amount of the fee associated with borrowing this item.
=item C<$currency = $item-E<gt>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.
=item C<$type = $item-E<gt>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
=item C<$mark = $item-E<gt>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
=item C<$msg = $item-E<gt>screen_msg>
=item C<$msg = $item-E<gt>print_line>
The usual suspects.
=back