[Koha-devel] Document Availability Information API

[Thomas Dukleth]

1.  KOHA HOLDINGS STRUCTURE.

The structure of the Koha database can be read even if not reliably
interpreted from kohastructure.sql,
http://git.koha.org/cgi-bin/gitweb.cgi?p=Koha;a=blob;f=installer/data/mysql/kohastructure.sql
.

If the intention is to have a system in which the user identifies user
appropriate copies by proximity and other relevant factors, the user would
need to first query for needed bibliographic records.  Ideally the
bibliographic records would be indexed centrally instead of running highly
inefficient distributed queries.  Acquire all the bibliographic records in
advance by whatever means seems suitable with frequent updates.

Koha currently has holdings in a single Koha holdings field within the
bibliographic records with some correspondence to MARC 21 bibliographic
holdings for MARC 21 and the French interlibrary loan standard
Recommandation 995 for UNIMARC.  The unified bibliographic and holdings
design within the bibliographic records has problems, but if you have the
MARC bibliographic records from a Koha installation then you should also
have the holdings embedded within them.

[Beware, Koha MARC 21 frameworks are overdue for an update and are
certainly missing what is needed for MAB2 unification.  Updating all the
variant frameworks for different material types in vim is a tedious time
intensive task which needs some time invested in improving the updating
process or better yet improving the design.  I have some not quite
finished work on updating MARC 21 frameworks which I did not commit over a
year ago and which now needs a few days work again.  German users
especially should be cautioned that data loss can result from incomplete
Koha MARC frameworks in some cases where records are saved within Koha for
which the MARC framework acts as a filter for the data from the record.]


1.1.  ITEM IDENTIFIER.

The default Koha MARC location for storing items.itemnumber is 952 $9 for
MARC 21 and 995 $9 for UNIMARC.  In case of library modification of the
Koha bibliographic frameworks, a reliable identification of the
items.itemnumber MARC field and subfield from a Koha Perl script would be
the following line.

my ($itemsMARCFieldID, $itemsItemnumberMARCSubfieldID) =
&GetMarcFromKohaField('items.itemnumber', '');

Avoid presuming that holdings information stored in the holdings field is
current.  Add a feature to Koha for querying the items table by itemnumber
in real time for whatever values you may need.


1.2.  ITEM NOTES.

Any item notes intended for the user should be presented to the user from
the MARC record stored.

The default Koha MARC location for items.itemnotes is 952 $z for MARC 21
and 995 $u for UNIMARC.  In case of library modification of the Koha
bibliographic frameworks, a reliable identification of the items.itemnotes
MARC field and subfield from a Koha Perl script would be the following
line.

my ($itemsMARCFieldID, $itemsItemnoteMARCSubfieldID) =
&GetMarcFromKohaField('items.itemnotes', '');

The default Koha MARC location for a periodical number, items.enumchron,
is not set for MARC 21, set to 995 $v for French UNIMARC, and not set for
English UNIMARC.  [Koha English UNIMARC frameworks are incomplete,
although, Recommandation 995 has been generally well specified within
them.]  In case of library modification of the Koha bibliographic
frameworks, a reliable identification of the items.enumchron MARC field
and subfield from a Koha Perl script would be the following line.

my ($itemsMARCFieldID, $itemsPeriodicalNumberMARCSubfieldID) =
&GetMarcFromKohaField('items.enumchron', '');


1.3.  LIBRARY BRANCH IDENTIFIERS.

Library location codes can be obtained from items.homebranch and
items.holdingbranch.  The branches table can be queried by branchcode for
information in the branchname, branchaddress1, etc. columns.  Except for
branchcode, the columns in the branches table should not be assumed to be
populated or current.


1.4.  LOCATIONS.

Location codes and location descriptions within the library can be queried
by itemnumber from the items table such as itemcallnumber and location
columns.  Electronic location is much more likely to be stored in MARC
field 856 than in items.uri.


1.5.  STATUS.

[Circulation is certainly not my speciality and it is generally the most
active area of development.  If I have some mistake, I hope that someone
will correct me.  There are certainly points of confusion where ordinary
language use of programmers has been used in the code which conflicts with
the prevalent library terminology.]


1.5.1.  REFERENCE OR CIRCULATING USE.

Whether an item may have reference or circulating use can be queried by
itemnumber from items.notforloan.

If items.notforloan is NULL, then the notforloan value for the Koha
itemtype should be checked.  The Koha itemtype could be identified by
itemnumber in items.itype.  If items.itype is NULL, then the Koha itemtype
may be found by itemnumber via the corresponding biblioitemsnumber in
biblioitems.itemtype.  Find the biblioitemsnumber to use by itemnumber in
the items table.  Once the itemtype is is identified, the notforloan value
can be found in by itemtype in itemtypes.notforloan.

Unfortunately, the meaning of the notforloan values is not well
standardised for Koha which achieves flexibility for individual libraries
at the price the ability to design useful circulation features for all
Koha libraries setting some useful values automatically.

MARC 21 notforloan defaults are:

-1  Ordered
 0  Circulating item
 1  Not For Loan
 2  Staff Collection

UNIMARC notforloan defaults have not been committed to Git.


1.5.2.  AVAILABLE STATUS.

Unavailable status of the item can be queried by itemnumber from the items
table for some reasons contained in the onloan (date value), damaged,
itemlost, withdrawn, and restricted columns.  Unavailable status from a
hold can be identified by itemnumber from the reserves table checking that
date of the reservedate column is not in the future and has no date set in
the cancellationdate column.

Taking some code from Koha C4::Search.pm may be useful for determining
availability, 
http://git.koha.org/cgi-bin/gitweb.cgi?p=Koha;a=blob;f=C4/Search.pm .  See
the searchResults() function, especially code following the comment "# For
each grouping of items (onloan, available, unavailable), we build a key to
store relevant info about that item".

Whether an item may be circulated involves many checks including lending
rules.  Taking some code from Koha C4::Circulation.pm may be useful,
http://git.koha.org/cgi-bin/gitweb.cgi?p=Koha;a=blob;f=C4/Circulation.pm .
 See code following the comment "# ITEM CHECKING" in the function
CanBookBeIssued().


1.5.3.  LOAN STATUS.

Status of a loan can be queried by itemnumber from the issues table such
as the date_due and renewals columns.  Additional information about
possible holds and additional renewals permitted by the current borrower
can be complex and liable to change in the next intermediate version. 
Obviously, the date due does not guarantee a return and there may be a lag
between the return of material to the library and the material being
properly reshelved.  Some helpful additional status clues may be obtained
by querying by itemnumber for issues.returndate and items.datelastseen.


2.  EXTENDING NCIP.

NCIP is an extensible standard even if not currently well suited for the
purpose intended.  Jacob, would you intend to extend NCIP with DAIA in
addition to making DAIA available independently?


Thomas Dukleth
Agogme
109 E 9th Street, 3D
New York, NY  10003
USA
http://www.agogme.com
+1 212-674-3783


[...]