C4/SIP/ILS/Item.pod

   1 =head1 NAME
   2
   3 ILS::Item - Portable Item status object class for SIP
   4
   5 =head1 SYNOPSIS
   6
   7         use ILS;
   8         use ILS::Item;
   9
  10         # Look up item based on item_id
  11         my $item = new ILS::Item $item_id;
  12
  13         # Basic object access methods
  14     $item_id    = $item->id;
  15     $title      = $item->title_id;
  16     $media_type = $item->sip_media_type;
  17     $bool       = $item->magnetic_media;
  18     $locn       = $item->permanent_location;
  19     $locn       = $item->current_location;
  20     $props      = $item->sip_item_props;
  21     $owner      = $item->owner;
  22     $str        = $item->sip_circulation_status;
  23     $bool       = $item->available;
  24     @hold_queue = $item->hold_queue;
  25     $pos        = $item->hold_queue_position($patron_id);
  26     $due        = $item->due_date;
  27     $pickup     = $item->hold_pickup_date;
  28     $recall     = $item->recall_date;
  29     $fee        = $item->fee;
  30     $currency   = $item->fee_currency;
  31     $type       = $item->sip_fee_type;
  32     $mark       = $item->sip_security_marker;
  33     $msg        = $item->screen_msg;
  34     $msg        = $item->print_line;
  35
  36     # Operations on items
  37     $status = $item->status_update($item_props);
  38
  39 =head1 DESCRIPTION
  40
  41 An C<ILS::Item> object holds the information necessary to
  42 circulate an item in the library's collection.  It does not need
  43 to be a complete bibliographic description of the item; merely
  44 basic human-appropriate identifying information is necessary
  45 (that is, not the barcode, but just a title, and maybe author).
  46
  47 For the most part, C<ILS::Item>s are not operated on directly,
  48 but are passed to C<ILS> methods as part of a transaction.  That
  49 is, rather than having an item check itself in:
  50
  51         $item->checkin;
  52
  53 the code tells the ILS that the item has returned:
  54
  55         $ils->checkin($item_id);
  56
  57 Similarly, patron's don't check things out (a la,
  58 C<$patron-E<gt>checkout($item)>), but the ILS checks items out to
  59 patrons.  This means that the methods that are defined for items
  60 are, almost exclusively, methods to retrieve information about
  61 the state of the item.
  62
  63 =over
  64
  65 =item C<$item_id = $item-E<gt>id>
  66
  67 Return the item ID, or barcode, of C<$item>.
  68
  69 =item C<$title = $item-E<gt>title_id>
  70
  71 Return the title, or some other human-relevant description, of
  72 the item.
  73
  74 =item C<$media_type = $item-E<gt>media_type>
  75
  76 Return the SIP-defined media type of the item.  The specification
  77 provides the following definitions:
  78
  79         000 Other
  80         001 Book
  81         002 Magazine
  82         003 Bound journal
  83         004 Audio tape
  84         005 Video tape
  85         006 CD/CDROM
  86         007 Diskette
  87         008 Book with diskette
  88         009 Book with CD
  89         010 Book with audio tape
  90
  91 The SIP server does not use the media type code to alter its
  92 behavior at all; it merely passes it through to the self-service
  93 terminal.  In particular, it does not set indicators related to
  94 whether an item is magnetic, or whether it should be
  95 desensitized, based on this return type.  The
  96 C<$item-E<gt>magnetic_media> method will be used for that purpose.
  97
  98 =item C<magnetic_media>
  99
 100 Is the item some form of magnetic media (eg, a video or a book
 101 with an accompanying floppy)?  This method will not be called
 102 unless
 103
 104     $ils->supports('magnetic media')
 105
 106 returns C<true>.
 107
 108 If this method is defined, it is assumed to return either C<true>
 109 or C<false> for every item.  If the magnetic media indication is
 110 not supported by the ILS, then the SIP server will indicate that
 111 all items are 'Unknown'.
 112
 113 =item C<$locn = $item-E<gt>permanent_location>
 114
 115 Where does this item normally reside?  The protocol specification
 116 is not clear on whether this is the item's "home branch", or a
 117 location code within the branch, merely stating that it is, "The
 118 location where an item is normally stored after being checked
 119 in."
 120
 121 =item C<$locn = $item-E<gt>current_location>
 122
 123 According to the protocol, "[T]he current location of the item.
 124 [A checkin terminal] could set this field to the ... system
 125 terminal location on a Checkin message."
 126
 127 =item C<$props = $item-E<gt>sip_item_props>
 128
 129 Returns "item properties" associated with the item.  This is an
 130 (optional) opaque string that is passed between the self-service
 131 terminals and the ILS.  It can be set by the terminal, and should
 132 be stored in the ILS if it is.
 133
 134 =item C<$owner = $item-E<gt>owner>
 135
 136 The spec says, "This field might contain the name of the
 137 institution or library that owns the item."
 138
 139 =item C<$str = $item-E<gt>sip_circulation_status>
 140
 141 Returns a two-character string describing the circulation status
 142 of the item, as defined in the specification:
 143
 144         01 Other
 145         02 On order
 146         03 Available
 147         04 Charged
 148         05 Charged; not to be recalled until earliest recall date
 149         06 In process
 150         07 Recalled
 151         08 Waiting on hold shelf
 152         09 Waiting to be re-shelved
 153         10 In transit between library locations
 154         11 Claimed returned
 155         12 Lost
 156         13 Missing
 157
 158 =item C<$bool = $item-E<gt>available>
 159
 160 Is the item available?  That is, not checked out, and not on the
 161 hold shelf?
 162
 163 =item C<@hold_queue = $item-E<gt>hold_queue>
 164
 165 Returns a list of the C<$patron_id>s of the patrons that have
 166 outstanding holds on the item.
 167
 168 =item C<$pos = $item-E<gt>hold_queue_position($patron_id)>
 169
 170 Returns the location of C<$patron_id> in the hold queue for the
 171 item, with '1' indicating the next person to receive the item.  A
 172 return status of '0' indicates that C<$patron_id> does not have a
 173 hold on the item.
 174
 175 =item C<$date = $item-E<gt>recall_date>
 176 =item C<$date = $item-E<gt>hold_pickup_date>
 177
 178 These functions all return the corresponding date as a standard
 179 SIP-format timestamp:
 180
 181         YYYYMMDDZZZZHHMMSS
 182
 183 Where the C<'Z'> characters indicate spaces.
 184
 185 =item C<$date = $item-E<gt>due_date>
 186
 187 Returns the date the item is due.  The format for this timestamp
 188 is not defined by the specification, but it should be something
 189 simple for a human reader to understand.
 190
 191 =item C<$fee = $item-E<gt>fee>
 192
 193 The amount of the fee associated with borrowing this item.
 194
 195 =item C<$currency = $item-E<gt>fee_currency>
 196
 197 The currency in which the fee type above is denominated.  This
 198 field is the ISO standard 4217 three-character currency code.  It
 199 is highly unlikely that many systems will denominate fees in more
 200 than one currency, however.
 201
 202 =item C<$type = $item-E<gt>sip_fee_type>
 203
 204 The type of fee being charged, as defined by the SIP protocol
 205 specification:
 206
 207         01 Other/unknown
 208         02 Administrative
 209         03 Damage
 210         04 Overdue
 211         05 Processing
 212         06 Rental
 213         07 Replacement
 214         08 Computer access charge
 215         09 Hold fee
 216
 217 =item C<$mark = $item-E<gt>sip_security_marker>
 218
 219 The type of security system with which the item is tagged:
 220
 221         00 Other
 222         01 None
 223         02 3M Tattle-tape
 224         03 3M Whisper tape
 225
 226 =item C<$msg = $item-E<gt>screen_msg>
 227
 228 =item C<$msg = $item-E<gt>print_line>
 229
 230 The usual suspects.
 231
 232 =back