Kyle Hall uses the case of Koha v. Libki to illustrate best practices for librarians looking to integrate two open source software systems in this chapter from editor Nicole Engard s More Library Mashups. Libki and Koha: Leveraging Open Source Software for Single Sign-on Integration Kyle M. Hall ByWater Solutions How does one go about getting two pieces of software to talk to each other? Pass them notes? Set them up on a blind date? It s unlikely that will work at least not until our computers become self-aware. If you are integrating two proprietary and/or closed source systems, you have a few options. If you are lucky, perhaps a protocol exists for those systems to speak to each other, and if you are really lucky, perhaps both systems already know how to speak the same language. Otherwise, be prepared to start writing checks! Likely, you ll need to pay one or both companies to get your systems to talk to each other, if they are even willing to work with and for you. If your two systems are both free and open source software, you have another choice: You can do it yourself, or if not you, someone on your team or perhaps a freelance developer. A good example of this type of integration can be found in the case of Koha v. Libki, which took place at the Crawford County Federated Library System in Pennsylvania. Koha (koha-community.org) is the first free and open source software library automation package, or integrated library system (ILS). Libraries of varying types and sizes, volunteers, and support companies from around the world sponsor the development and growth of Koha. The name comes from the Māori term for a gift or donation. Libki (libki.org) is is a free and open source kiosk management system, with a web-based administration system and a cross-platform 261
262 More Library Mashups client. Libki is ideally suited for use in locations where a controlled computing environment is paramount, such as public access systems, libraries, school computer laboratories, and more. The pre 1.0 version of Libki did not have Session Initiation Protocol (SIP) support built in like it does today, so something more tricky, more clever, and more hackerish had to be devised to get it to communicate with Koha. Crawford County in Pennsylvania has nine libraries, all sharing one Koha ILS server located in the most central location in the county, Meadville. Many of these libraries also use the Libki Kiosk Management System to time limit computer access, and these Libki servers are found on site at each library in the county. The libraries want single sign-on between all these systems, yet no protocol that could accomplish this is supported between the two. So how do we accomplish this task? We start hacking. Planning The first task in this scenario is to decide which system is considered the primary source of information in other words, from which system will the rest of the system receive information and update itself? In this case, the obvious choice is the Koha server, because not only do we have a single Koha server and many Libki servers, but because the data the Koha server stores far exceeds that of our Libki servers. Koha stores detailed information about all library patrons: names, addresses, birth dates, and so on. Libki, on the other hand, stores a very minimal amount of data such as usernames and passwords. Since the only pieces of information we need to transmit are usernames and passwords, this works very well. Our next job is to locate how and where that information is stored in both systems, and also to locate the (hopefully singular) points in the software s source code where these values get modified. In Koha, we can find this data in the MySQL database table Borrowers under the columns User ID and Password. The password is not stored in plain text, of course that would be a terrible violation of security practices. Instead, if one examines the code for Koha 3.12 (the latest version at the time of this writing) or earlier, they will see that all passwords in Koha are hashed using md5 and then
Libki and Koha: Leveraging Open Source Software 263 encoded in base64 by the aptly named function md5_base64, which is provided by the Perl library Digest::MD5. In Libki < 1.0, the users are stored in the database table logins, using the columns Username and Password. As luck would have it, Libki also uses this same password storage scheme. If we had not been so lucky, we would still be able to accomplish our task, but it would have been slightly more difficult. So, now that we know all about the data we are storing, we need to know where said data is created, updated, and deleted from within Koha. Those are the places where we need to set up triggers to update our Libki servers. In the case of Koha, we have three subroutines dealing with this in the Members module of Koha: AddMember, ModMember, and DelMember respectively. In each of those subroutines, we add the following code: if (C4::Context->preference('LibkiIntegration')) { my $borrowernumber = $data{borrowernumber; C4::Libki::UpdateForLibki($borrowernumber); This is just a fancy way of saying, If we ve enabled integration between Koha and Libki, and we are changing this user in some way, run the subroutine UpdateForLibki for this account. So what is in the C4::Libki module, you may ask? Not much. Here is the source code for said module: package C4::Libki; Copyright 2011 Kyle M Hall <kyle@kylehall.info> This file is part of Koha. Koha is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later
264 More Library Mashups version. Koha is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Koha; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. use strict; use warnings; use C4::Context; use vars qw($version @ISA @EXPORT); BEGIN { set the version for version checking $VERSION = 1.01; require Exporter; @ISA = qw(exporter); @EXPORT = qw(&updateforlibki); sub UpdateForLibki { my ($borrowernumber) = @_; my $dbh = C4::Context->dbh; my $sql = "INSERT INTO libki_queue (borrowernumber) VALUES (?)" my $sth = $dbh->prepare($sql); $sth->execute($borrowernumber);
Libki and Koha: Leveraging Open Source Software 265 1; END So to put it succinctly, UpdateForLibki simple puts the unique identifier into a new and special table we ve created just for this task. Yes, we could have put this code directly into each of the previously mentioned subroutines, but doesn t it look so much prettier this way? At this point, we have a list of all the accounts in Koha that need to be created, updated, or deleted in all of our respective Libki servers. The next task on our docket is to accomplish just that. How do we do this? With a daemon of course! The friendly, useful kind not the fiery damn-you-to-eternal-pain-and-torture kind. For the uninitiated, a daemon is a computer program that runs as a background process, rather than being a program that you run and control interactively. For example, at a restaurant, you could say your server is a program you interact with when you give that server your order. The server writes down your order and walks over to the kitchen window where he puts that order on one of those order wheels with the clips (and thus is revealed my deep understanding of restaurant nomenclature). The chef waits in the background, notices a new order is coming in, and begins preparing the food. In this example, our chef is much like a daemon, lurking in the background, waiting to spring into action. Here is our daemon:!/usr/bin/perl use strict; use warnings; use File::Basename; use Fcntl qw(lock_ex LOCK_NB); use C4::Context; use constant SLEEP_INTERVAL => 15;
266 More Library Mashups my $daemon = basename($0); open(selflock, "<$0") or die("couldn't open $0: $!\n"); flock(selflock, LOCK_EX LOCK_NB) or die("aborting: another $daemon is already running\n"); Get ready to daemonize by redirecting our output to syslog, requesting that logger prefix the lines with our program name: open(stdout, " -", "logger -t $daemon") or die("couldn't open logger output stream: $!\n"); open(stderr, ">&STDOUT") or die("couldn't redirect STDERR to STDOUT: $!\n"); $ = 1; Make output line-buffered so it will be flushed to syslog faster Avoid the possibility of our working directory resulting in keeping an otherwise unused filesystem in use chdir('/'); Double-fork to avoid leaving a zombie process behind: exit if (fork()); exit if (fork()); sleep 1 until getppid() == 1; print "$daemon $$ successfully daemonized\n"; my $dbh = C4::Context->dbh; my $sth; while (1) { while (! $dbh->ping) { $dbh = C4::Context->dbh;
Libki and Koha: Leveraging Open Source Software 267 $sth = $dbh->prepare("select * FROM libki_ queue"); $sth->execute(); while (my $r = $sth->fetchrow_hashref) { my $borrowernumber = $r->{'borrowernumber'; exec("koha2libki_update.php $borrowernumber & "); $dbh->do( "DELETE FROM libki_queue WHERE borrowernumber = $borrowernumber" ); sleep(sleep_interval); So what does all this fantastical nonsense accomplish? Every 15 seconds, it checks the table libki_queue (our order wheel) to see if there are any user identifiers ( borrowernumber in our case) in there. For each of these identifiers it finds, the daemon creates another process, which calls the script koha2libki_update.php to handle the real update for each of the Libki servers. You may have noticed all our code examples so far have been written in Perl, but we are now executing a PHP script. Why, you may ask? That is because Koha is written in Perl, but the script we are calling was included with Libki, which is written in PHP. Here is that script:!/usr/bin/php <?php This file is part of Libki. Libki is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
268 More Library Mashups Libki is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Libki. If not, see <http://www.gnu. org/licenses/>. Get borrowernumber from arguments $borrowernumber = $argv[1]; if (empty($borrowernumber)) { die ("No borrowernumber given!\n"); The libki ini file contains a section for each of our Libki servers $libki = parse_ini_file("/etc/libki/libki.ini", $process_sections=true) or die("unable to parse / etc/libki/libki.ini\n"); The koha ini file contains just data about how to connect to our Koha server's database $koha = parse_ini_file("/etc/libki/koha.ini"); Open the Koha database $kdbh = mysql_connect($koha["host"], $koha["username"], $koha["password"]) or die("unable to connect to Koha MySQL Server\n"); mysql_select_db($koha["database"], $kdbh); Grab the userid and password of the user based on the borrowernumber $query = "SELECT userid, password FROM borrowers WHERE borrowernumber = '$borrowernumber'";
Libki and Koha: Leveraging Open Source Software 269 $results = mysql_query($query, $kdbh); $result = mysql_fetch_assoc($results); $userid = $result['userid']; $password = $result['password']; foreach ($libki as $ini) { Open the LibKi database $ldbh = mysql_connect($ini["host"], $ini["username"], $ini["password"]); mysql_select_db($ini["database"], $ldbh ; if ($userid) { Get default starting minutes from database $query = "SELECT value FROM settings WHERE name = 'daily_minutes'"; $results = mysql_query($query, $ldbh); $result = mysql_fetch_assoc($results); $daily_minutes = $result['value']; Check to see if this user is already in libki $query = "SELECT COUNT(*) AS userexists FROM logins WHERE username = '$userid'"; $results = mysql_query($query, $ldbh); $result = mysql_fetch_assoc($results); $userexists = $result['userexists']; If the user doesn't already exist, create the user in libki if (! $userexists) { $query = "INSERT INTO logins (username, units, status, password) VALUES ('$userid', '$daily_minutes', 'Logged out', '$password')"; mysql_query($query, $ldbh); else { Copy over the koha password $query = "UPDATE logins SET password = '$password' WHERE username = '$userid'"; mysql_query($query, $ldbh);
270 More Library Mashups else { User no longer exists in Koha, delete this user from Libki $query = "DELETE FROM logins WHERE username = '$userid'"; mysql_query($query, $ldbh);?> What this script does, in layman s terms, is take a user identifier and look it up in our Koha database. If it finds it, it then calls out to each of the Libki server s databases and says Hey you! Yeah, I m talking to you! Does this user exist in your database? The Libki database then replies with Yeah! I got your user right here! or Heck no, we ain t got no user like that! It s quite obvious that our Libki database did not go to an Ivy League school. Once we know if the user exists or not, we can then tell the Libki database to update the existing user s password or to create the new user with the given username and password data, respectively. To satisfy your curiosity, here is an example of what the libki.ini file would look like for a system with three libraries: [LibraryA] host = libki.librarya.mylibrarysystem.org username = libkiadmin password = apoorlychosenpassword database = libki [LibraryB] host = libki.libraryb.mylibrarysystem.org username = libkiadmin password = anothernotsogoodpassword database = libki [LibraryC] host = libki.libraryc.mylibrarysystem.org username = libkiadmin password = theworstpasswordyet database = libki
Libki and Koha: Leveraging Open Source Software 271 Each Libki installation could have, in theory, a different username and database name, but why mess with success? Conclusion If you are a programmer, you may be saying Wow, I could have done a way better job than this. What a mess! To that I would reply Cut me some slack! I was in a hurry! It works, doesn t it? Why do you have to kick me right in the self-esteem? Indeed, I m sure there are many ways to improve and streamline this system, but it is merely an example of what can be accomplished when you leverage the power of free and open source software. To reiterate our basic process, this is what we did: 1. Identify our data A. Identify our source data B. Identify our target data 2. Identify our relevant source code A. Identify data creation code B. Identify data modification code C. Identify data deletion code 3. Create a shim to communicate our source data to our targets A. Insert code to call shim for each data alteration B. Shim checks to see which action needs to be taken C. Shim implements said action In our example (Figure 18.1), we were lucky in that both our source and target data were stored in MySQL databases. In the open source world, it is common for data to be stored in an open source DBMS such as MySQL or PostgresSQL. For other software where you cannot get direct access to the data, you may need to identify a service API you could call on instead. Remember, there s always more than one way to do it.
272 More Library Mashups Figure 18.1 Data flow from Koha to Libki I hope you ve been informed and amused by my incoherent ramblings. And I hope my example illustrates how it s almost always possible to make two systems work together if you put your mind to it! About the Author Kyle M. Hall received his MS in Information Technology from Edinboro University (PA). He has been fulfilling the IT needs of librarians for over a decade at the Crawford County Federated Library System as an IT specialist and Koha developer. His work has not only included enhancing Koha itself but also authorship of the Koha Offline Circulation tool and the maintenance of the Koha Virtual Appliance. He is also the sole author of Libki. This chapter originally appeared in More Library Mashups: Exploring New Ways to Deliver Library Data, edited by Nicole C. Engard. For more information visit http://books.infotoday.com.