Document Availability Information API

[Jakob Voss-4]

Hi,

I just sent this mail to Code4Lib mailing list that not everyone may
follow. I am not familiar with Koha source code and database internals
so could you point me to where availability status and such (loan period
and queue, call number, location...) is stored?

I just wanted to announce that I finished a reference implementation of
the Document Availability Information API (DAIA) as CPAN module at
http://search.cpan.org/perldoc?DAIA. More information about DAIA can be
found in the specification at http://purl.org/NET/DAIA and at
http://www.gbv.de/wikis/cls/DAIA. The basic structure is:

[Document] -- 1-to-n --> [Item]
[Item ]-- 1-to-n --> [Service] (which is either [Available] or
[Unavailable])

We created DAIA for German library networks as interchange format and
API to encode information about the current availability of a specific
document (or any copy of it) in a given library. There are numerous APIs
for several tasks in library systems (SRU/SRW, Z39.50, OpenSearch,
OAI-PMH, Atom, unAPI etc.) but no standard way to just query whether a
copy of given - for instance book - is available in a library, in which
department, whether you can loan it or only use it in the library (or
even read it online) or if it is not available how long it will probably
take until it is available again. Obviously such an API would be helpful
not only to connect different library systems but to create mashups and
services ("Show me on a map, where a given book is currently hold and
available", "Send me a tweet if a given books in my library is available
again" etc.). DAIA was createt to fill this gap. In the context of ILS
Discovery Interface Task Force and its official recommendation
(http://diglib.org/architectures/ilsdi/) DAIA fits to the
GetAvailability method (section 6.3.1).

At the moment the format and API are pretty stable so the main work is
to create server and client components for several ILS software. Every
library has its own special rules and schemas - Jonathan Rochkind
already wrote about the problems to implement DAIA because of ILS
complexity:
http://bibwild.wordpress.com/2009/09/02/daia-and-ils-complexity/ . We
cannot erase this complexity by magic (unless we refactor and clean the
ILS) but at least we can try to map it to a common data model which DAIA
provides. With the DAIA Perl package you can concentrate on writing the
wrapper without dealing with DAIA parsing and serialization issues. Why
should everyone write its own routines to grab for instance the HTML
OPAC output to parse availability status? One mapping to DAIA should fit
most needs, so others can build upon. A public DAIA converter/validator
is available at http://ws.gbv.de/daia/validator

Extensions to DAIA can be discussion in the Code4Lib Wiki
http://wiki.code4lib.org/index.php/DAIA_extensions but I'd prefer no to
start with the extensions but with basic services. If you have more cool
ideas for client applications, just let me know!

Cheers,
Jakob

P.S: Yes, there are some other awkward attemts to encode availability
(Z39.50 Holdings, ISO 20775 Holdings, NCIP, SLNP...) but I found all of
them  underdefined and not publically documented or openly usable based
on Web standards.

--
Jakob Voß <jakob.voss@...>, skype: nichtich
Verbundzentrale des GBV (VZG) / Common Library Network
Platz der Goettinger Sieben 1, 37073 Göttingen, Germany
[phone], http://www.gbv.de
_______________________________________________
Koha-devel mailing list
Koha-devel@...
http://lists.koha.org/mailman/listinfo/koha-devel

[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
[phone]


[...]


_______________________________________________
Koha-devel mailing list
Koha-devel@...
http://lists.koha.org/mailman/listinfo/koha-devel