2004-12-17 Stephen Hedges shedges AT skemotah.com 2.0.0p1 2004-12-17 sh Minor changes, mostly in the Copyright and License section 2.0.0 2004-11-08 sh Initial XML markup of HTML document

Copyright 2004 Stephen Hedges shedges (at) skemotah.com This document is related to Koha and is licensed to you under the GNU General Public License version 2 or later (http://www.gnu.org/licenses/gpl.html). Koha-related documents may be reproduced and distributed in whole or in part, in any medium physical or electronic, as long as this copyright notice is retained on all copies. You may create a derivative work and distribute it provided that you: License the derivative work with this same license, or the Linux Documentation Project License (http://www.tldp.org/COPYRIGHT.html). Include a copyright notice and at least a pointer to the license used. Give due credit to previous authors and major contributors. Commercial redistribution is allowed and encouraged; however, the author would like to be notified of any such distributions.

No liability for the contents of this document can be accepted. Use the concepts, examples and information at your own risk. There may be errors and inaccuracies, that could be damaging to your system. Proceed with caution, and although this is highly unlikely, the author(s) do not take any responsibility. All copyrights are held by their by their respective owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark. Naming of particular products or brands should not be seen as endorsements.

Koha version 2.0.0 is an open source integrated library system (ILS) for automating a lending library. It has all of the basic features needed to run a library, handling: an online public access catalog (OPAC) of the library's holdings; a database of library users; issuing books to borrowers and returning books to the collection; borrower requests for library items; orders from vendors; book budgets; transfers between library branches; and most other functions associated with operating a lending library. Koha ver.2.0.0 supports MARC21 and UNIMARC bibliographic records. While there are still a few ILS products that use their own format for storing bibliographic data, most commercial products have adopted some version of the venerable MARC (MAchine Readable Cataloging) record standard. Beginning with version 2.0.0, Koha supports MARC records, specifically records following the MARC21 and UNIMARC standards. Koha is currently in use in several small to medium size libraries with as many as 130,000 bibliographic records and 40,000 borrower records. At the time of this writing (early 2004), it lacks support for Library of Congress classification, using the Dewey Decimal System instead, meaning that it is best-suited for schools and public libraries. The current code is maintained on Sourceforge.

The main attraction of Koha is that it is free, since it is open source software. It is best to think of it as "free to change" however, rather than "free of cost" It is possible to set up a functioning Koha system without spending any money, but you will still spend more time on the implementation than you would with a commercial ILS (where you are paying the software vendor to set it up for you), and you will need to have a pretty fair knowledge of web server software (usually Apache) and the Perl programming language in order to configure some parts of Koha. Some knowledge of MySQL is also handy for database maintenance chores. Most libraries should probably plan on investing time, training, and some money before they have Koha up and running. That being said, Koha is still much less expensive than commercial library software, especially when you consider that there are no annual license fees. The best reason to migrate from a commercial system to Koha is the fact that you will have complete control over your library software. Because the entire source code is open, a library can modify Koha to do things as the library wants them done. Commercial systems must aim their research and development for the "middle of the market," where most of their business can be found. But a library that wants to surpass the capabilities of most other libraries will find that Koha provides the freedom to try boldly imaginative innovations in library service.

This document assumes that you have already installed a Koha system and have an existing ILS, and now wish to transfer your data from the old system to Koha. There are no instructions in this document, therefore, for installing and configuring the basic Koha parameters. (The most recent instruction set should be available at koha.org/manual. There is also a very good guide for installing Koha on Debian available from Joshua Ferraro.) Nor are there any instructions for entering new data or using Koha's Z39.50 client to retrieve MARC records from a Z39.50 server. If you are planning to build such "new" data instead of transferring data from an existing system, however, parts of this document will still be helpful in explaining how Koha stores bibliographic and patron data. Once you have installed the software and are able to run it, you will need to set up your system parameters on the administration page (cgi-bin/koha/admin-home.pl). Some of these, such as the book funds and budget, currencies, authorized values, etc., can be done if and when you choose to use those features of Koha. Others need to be done before you can import data into Koha and use it. These essential parameters are: Item types; MARC tag structure (and Koha to MARC links); Library branches; Borrower categories; Stop words; and System preferences.

The item types are the "categories" into which your library items fall. For instance, you probably want to have videocassettes in a different category from non-fiction books, and mysteries in a different category from children's picture books. If you already are using a commercial ILS, you almost certainly already have all of your materials divided up into such categories. Now you need to tell Koha what your categories are. This is more important than it sounds. Much of Koha simply does not work right unless your item types are defined and every item has some type designated. Small things like loan periods and item counts become big headaches if you haven't set up your item types. There's good reason for this being at the top of the Koha parameters page! As you add item types to Koha, you should be aware that the type code is limited to four characters. This code is rarely displayed by Koha; instead the description of the type will be what users see. Loan length is specified as a number of (calendar) days and the rental charge is just what it sounds like, any amount you might charge to users for borrowing items of a certain type (like videos). Renewals allowed is a yes/no question on the administration page (check the box if items of this type can be renewed). What actually happens when the item type is saved is that a number is saved in the renewalsallowed column in the itemtypes table of the Koha MySQL database: yes=1 and no=0. But this number is also used by the code to determine how many times an item can be renewed. If your library allows items to be renewed more than once, then you will have to manually edit the itemtypes table to reflect this. For example, if you allow some item types to be renewed twice, you need to manually change the value of renewalsallowed from 1 to 2.

Koha allows you to specify which MARC tags you want to use and which you want to ignore. When you downloaded and installed Koha, you also got the entire list of MARC21 tags and subfields in current use. Now you need to use the administration page to edit this list and tell Koha which tags you want to use and how you want to use them, or modify the tags to conform to UNIMARC standards. If you are CERTAIN that you will never use a MARC tag, then you can delete it, but since this will not result in any appreciable improvement in performance, it is probably better to leave it. There will be tags you want to add, however. If you are using older MARC tags that are not in the list of tags supplied with Koha, then use the MARC tag structure administration page (cgi-bin/koha/admin/marctagstructure.pl) to add them. Similarly, you will probably need to add the holdings tag you currently use, or at least check the subfield structure of the 852 tag if you use it for holdings. Editing the subfields from the MARC tag structure page is very important (cgi-bin/koha/admin/marc_subfields_structure.pl). It is also a very time-consuming process, but one that is absolutely necessary if you want your Koha installation to behave as intended. As an ilustration, here is a possible subfield structure for the 245 "title statement" tag: SELECT tagsubfield,kohafield,tab FROM marc_subfield_structure WHERE tagfield=245; +-------------+-------------------------+------+ | tagsubfield | kohafield | tab | +-------------+-------------------------+------+ | 6 | | -1 | | 8 | | -1 | | a | biblio.title | 1 | | b | bibliosubtitle.subtitle | 1 | | c | | 1 | | f | | -1 | | g | | -1 | | h | biblio.abstract | 1 | | k | | -1 | | n | | 1 | | p | | 1 | | s | | -1 | +-------------+-------------------------+------+ To focus on the important information, the query above does not show the "lib for librarians" and "lib for OPAC" values (what the librarian or OPAC user will see as the subfield description) or the repeatable and mandatory values (always either yes or no, represented by 1 or 0 in the database). The standard MARC21 subfield descriptions and repeatabilty are supplied with Koha, and if you require that every one of your MARC records have a particular subfield, then you should set that subfield to mandatory. The "non-standard" information here is the Koha field and the tab. The kohafield column holds any mapping between the MARC tables in the database and the original Koha tables. MARC records are capable of holding much more information than the original, non-MARC Koha tables. For standard searching and display of brief bibliographic information, however, the original Koha tables are usually adequate. Therefore, instead of rewriting most of the scripts and modules in Koha version 1.9 to make the MARC-compatible version 2.0, the developers set up a separate table (marc_subfield_value) to hold the MARC record data, and linked that data to the original Koha tables, so the original scripts and modules could still be used. In the example above, the 245a MARC tag and subfield is linked (mapped) to the title column in the original Koha biblio table, and the 245b tag is linked to the subtitle column in the bibliosubtitle table. This means that every time a new MARC record is loaded into the database, any information that is in the 245a tag is also stored in a corresponding record in the biblio table, and anything in the 245b tag also gets stored in the bibliosubtitle table. We just said that the original Koha tables are "usually adequate" for storing enough bibliographic information to construct brief displays. In the example above, however, you can see a "work-around" for an instance in which the Koha tables were not adequate. In the particular installation of Koha from which this example was taken, it was decided that it was important to store the 245h "material designation" tag in the original Koha tables so it could be displayed in the first list of results of any search. The material designation would tell the searcher if the bibliographic item shown was something other than a book, such as a sound recording or a videorecording. Since there was no other place to store this information, an otherwise unused Koha column was selected (the abstract column in the biblio table), and the templates that build the search results displays were altered accordingly. (As with Perl, with Koha there is always more than one way to do things!) Once you have decided which MARC subfields to map to Koha columns, don't use the MARC tag structure page to do it. While it is possible to do it here, Koha has a separate Links Koha-MARC DB page (cgi-bin/koha/admin/koha2marclinks.pl) that you can access from the parameters page (admin-home.pl). This interface is a much easier and safer way to set up your MARC to Koha mapping. The tab column holds either a -1 or a number from 0 to 10. "Tab" is used here in the sense of a tab in a web browser, not a tab in a text processor. It controls how MARC tags and subfields are grouped and displayed when the librarian or cataloger is working with the MARC records. Any tags and subfields that you want to have available for editing or displaying in the MARC display pages need to have a value between 0 and 9. A -1 value means the subfield is ignored when building such pages. While you could give all the other subfields (with the exception of subfields in your item information tag) the same value, all these subfields, whether empty or not, would display every time you wanted to edit or display your MARC record, making a very long web page! It is best to subdivide your MARC tags and subfields into logical groups that are then displayed on separate pages in their own "tabs." Here are a couple of examples to illustrate one way to do this: SELECT tagfield,tagsubfield,tab FROM marc_subfield_structure WHERE tab=0; +----------+-------------+------+ | tagfield | tagsubfield | tab | +----------+-------------+------+ | 010 | a | 0 | | 010 | b | 0 | | 020 | a | 0 | | 022 | a | 0 | | 024 | a | 0 | | 024 | d | 0 | | 028 | a | 0 | | 028 | b | 0 | | 035 | a | 0 | | 082 | a | 0 | | 082 | b | 0 | | 100 | a | 0 | | 100 | d | 0 | | 110 | a | 0 | +----------+-------------+------+ SELECT tagfield,tagsubfield,tab FROM marc_subfield_structure WHERE tab=1; +----------+-------------+------+ | tagfield | tagsubfield | tab | +----------+-------------+------+ | 245 | a | 1 | | 245 | b | 1 | | 245 | c | 1 | | 245 | h | 1 | | 245 | n | 1 | | 245 | p | 1 | | 246 | a | 1 | | 246 | b | 1 | | 246 | h | 1 | | 250 | a | 1 | | 250 | b | 1 | | 256 | a | 1 | | 260 | a | 1 | | 260 | b | 1 | | 260 | c | 1 | | 300 | a | 1 | | 300 | b | 1 | | 300 | c | 1 | | 300 | e | 1 | | 300 | f | 1 | | 300 | g | 1 | | 440 | a | 1 | | 440 | n | 1 | | 440 | v | 1 | | 490 | x | 1 | | 490 | v | 1 | | 490 | a | 1 | +----------+-------------+------+ ...and so forth. The tab value 10 is reserved for the item information from your holdings tag subfield, since this information is always displayed on a separate page when editing or displaying MARC records. There's one other chore you need to take care of before you are ready to load data, and that is checking to make sure the barcode column in the items table is big enough to hold your barcodes. If your barcodes are longer than the space allowed, you will need to alter the items table accordingly.

Obviously, if you have an existing ILS, you have a lot of valuable data that you have collected that you will want to transfer into Koha. This process may be the most complex and costly part of migrating to Koha, and is unfortunately an area where this document will be of relatively little help. Each vendor's product handles data differently, with variations in database structure, database software, and exporting tools. You may well find that you will need top pay your current vendor to prepare your data for export, with no recourse to any other solution because their software source code is closed and proprietary. Still, there are a few general comments about data extraction that will be helpful in planning and negotiating the process of exporting your data. There are basically three types of data you will want to retrieve from your old system: bibliographic records; user information; and transaction records.

Since it is assumed that you are already using a commercial ILS and are migrating to the most current version of Koha, the following remarks pertain to preparing existing MARC records for import into Koha. Koha version 2.0.0 makes extensive use of the MARC::Record Perl package for reading, checking, and processing records for import. This collection of Perl modules is designed to work with MARC data in transmission format, more accurately "ISO 2709 exchange format," which is the MARC data in a format that's easy for computers to pass back and forth, though not so easy for humans to read. As the name "ISO 2709" implies, this is an international standard for formating bibliographic records; your current ILS vendor should have tools available to export your bibliographic records in ISO 2709 format (or you should demand to know why they are not conforming to international standards!). Getting your records -- your complete records, including holdings information -- in ISO 2709 format is the essential first step in importing your bibliographic information into Koha. If for some strange reason your current ILS is incapable of dumping records in ISO 2709 format, but can do ASCII or some other widely recognized format, you may be lucky enough to be able to use some of the tools listed by the Library of Congress for manipulating MARC records and do the conversion to ISO 2709 yourself. Most likely, however, you will find that your vendor can supply the tools you need for exporting your records in the standard exchange format, though they may ask for a fee before providing them. Once you have your records in ISO 2709 format, you will work from a command line on your Koha server and run the bulkmarcimport.pl script that comes with Koha to load your records. The command to use is: KohaFolder/intranet/scripts/misc/bulkmarcimport.pl -file YourISO2709fileName -- where KohaFolder is the name of the directory or folder where you installed Koha (such as /usr/local/koha) and YourISO2709fileName is the name (and location) of the file of MARC records dumped from your old ILS. If you intend to make any changes to the structure of your MARC records (for example, you want to change your holdings tag structure), this should be done before you import the records. Again, the Library of Congress tools may be helpful. If you are reasonably adept at Perl programming, or are willing to pay a small fee to someone who is, you can also use the MARC::Record Perl package to rebuild your records. Either way, the point is the same: make any changes before you import your records, by making changes to the ISO 2709 file itself. The bulkmarcimport.pl script is also a handy place to start if you want to write a script to import records on a regular basis. This might be the case if you use a different utility to generate new MARC records and then do regular imports of those records into Koha. Because of differences between MARC records and Koha records, you will find that some pieces of information do not import cleanly with the 'plain' bulkmarcimport.pl utility. For example, MARC publication dates often have a 'c' (for 'copyright') in front, so bulkmarcimport.pl will place 'c1999' in the Koha publication date column in the database. (This is assuming that you have mapped MARC tag 260c to biblioitems.publicationyear.) Koha can select catalog records by publication year, but only if the publication year is a number, so entries like 'c1999' would not be selected. While it is easy enough to correct this after the initial import of your records by using the MySQL TRIM function, you won't want to be doing this kind of 'clean-up' work on a regular basis, when you can modify the bulkmarcimport.pl script to do it when the records are loaded. As of this writing, the Koha import process does not handle multiple subject entries very well. In general, while a MARC record may have many subject entries, only one currently gets loaded into the Koha subjects table (bibliosubject). Again, this can be remedied by modifying the bulkmarcimport.pl script if you are good at Perl. (Or, at the risk of being repetitious, you are willing to hire someone who is.) Since this document was first written, newer versions of Koha have been released which do catalog searches directly against the MARC record, instead of the old Koha tables, so loading of data into the subjects table is less important. If you are getting ready to do some complex things with your records, you need to know a little about Koha's database tables for storing records: +-------------------------+ | Bibliographic Tables | +-------------------------+ | additionalauthors | | biblio | | biblioanalysis | | biblioitems | | bibliosubject | | bibliosubtitle | | bibliothesaurus | | catalogueentry | | deletedbiblio | | deletedbiblioitems | | deleteditems | | items | | itemsprices | | marc_biblio | | marc_blob_subfield | | marc_subfield_table | | marc_word | +-------------------------+ Many of the table names are self-explanatory, but some are not. The three primary 'old-Koha' tables are; biblio, which holds the basic bibliographic information such as title, author, etc.; biblioitems, which holds more specific information such as format, publication year, item type, etc.; and items, which holds information about specific items, such as barcode number, price, date acquired, etc. These three tables are linked together by a common 'biblionumber.' You may have a biblio entry for The Two Towers, several biblioitems entries that link to it (perhaps one for the book, one for the audio recording, one for the large print edition), and multiple items (copies) for each biblioitem. This structure mirrors some aspects of the International Federation of Library Associations' Functional Requirements for Bibliographic Records (FRBR). MARC records do not have such a structure, but instead have a basic record, which would contain the information that Koha would keep in the biblio and biblioitems tables, and a holdings tag, which would contain the information in Koha's items table. Koha stores MARC records in the marc_subfield_table table, which breaks the record down into tags and subfields and then links everything back together using a single 'bibid' for all the pieces. The marc_biblio table keeps track of the relationship between the bibid of the MARC record and the biblionumber of the corresponding information that has been stored in the old-Koha tables. There are also two general "keyword" tables that serve somewhat as indexes, storing each word in a record with the biblionumber or bibid of the record it came from. For items cataloged using the old-Koha interface, these words are stored in catalogueentry, while words from MARC records (either imported or cataloged using the MARC interface) are stored in marc_word.

Unlike bibliographic records, there is as yet no commonly used standard for user records, though the relatively new NCIP standard addresses some aspects of user information and may become as widespread as MARC records someday. Meanwhile, this is an area where you will have to dig out as much information as possible from your existing database, using whatever means possible. If you are fortunate enough to have some sort of export utility with you current ILS, you just need to determine that it exports all the data you want. Most likely, however, you have no such utility and will have to either access your database directly and dump the data you need (if possible) or ask your current vendor to do it for you. In any case, you will want to retrieve the following information about your users: names (first names, last name, and perhaps title); library card number; user ID (if different from library card number); street address; mailing address, or any other alternate address you might have on file; date of birth (if available); telephone number; user category code (e.g. 'A' for adult); date enrolled (if available); branch where enrolled (if available); any status codes (e.g. blocked, bad address, etc.); user password (if available in plain text); preferred method of contact (if available); any notes. This information will then need to be loaded into the Koha borrowers table. The columns in this table are a little confusing, since the table has been expanded at various times to accomodate the needs of libraries needing to store more information and therefore needing more columns in the table. Here is the current table structure, with some notes on what the columns can contain: SHOW COLUMNS FROM borrowers; +------------------+--------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +------------------+--------------+------+-----+---------+----------------+ | borrowernumber | int(11) | | MUL | NULL | auto_increment | | cardnumber | varchar(9) | | MUL | | | | surname | text | | | | | | firstname | text | | | | | | title | text | YES | | NULL | | | othernames | text | YES | | NULL | | | initials | text | | | | | | streetaddress | text | | | | | | suburb | text | YES | | NULL | | | city | text | | | | | | phone | text | | | | | | emailaddress | text | YES | | NULL | | | faxnumber | text | YES | | NULL | | | textmessaging | text | YES | | NULL | | | altstreetaddress | text | YES | | NULL | | | altsuburb | text | YES | | NULL | | | altcity | text | YES | | NULL | | | altphone | text | YES | | NULL | | | dateofbirth | date | YES | | NULL | | | branchcode | varchar(4) | | | | | | categorycode | char(2) | YES | | NULL | | | dateenrolled | date | YES | | NULL | | | gonenoaddress | tinyint(1) | YES | | NULL | | | lost | tinyint(1) | YES | | NULL | | | debarred | tinyint(1) | YES | | NULL | | | studentnumber | text | YES | | NULL | | | school | text | YES | | NULL | | | contactname | text | YES | | NULL | | | borrowernotes | text | YES | | NULL | | | guarantor | int(11) | YES | | NULL | | | area | char(2) | YES | | NULL | | | ethnicity | varchar(50) | YES | | NULL | | | ethnotes | varchar(255) | YES | | NULL | | | sex | char(1) | YES | | NULL | | | expiry | date | YES | | NULL | | | altnotes | varchar(255) | YES | | NULL | | | altrelationship | varchar(100) | YES | | NULL | | | streetcity | text | YES | | NULL | | | phoneday | varchar(50) | YES | | NULL | | | preferredcont | char(1) | YES | | NULL | | | physstreet | varchar(100) | YES | | NULL | | | homezipcode | varchar(25) | YES | | NULL | | | zipcode | varchar(25) | YES | | NULL | | | userid | varchar(30) | YES | | NULL | | | password | varchar(30) | YES | | NULL | | | flags | int(11) | YES | | NULL | | +------------------+--------------+------+-----+---------+----------------+ borrowernumber This value is automatically generated when a patron is added. To add patrons in bulk, however, you may need to generate this number manually. For instance, if you put your patron information into a comma-delimited file and use MySQL's "LOAD DATA INFILE" command to load your data (a very fast operation!), the first comma-delimited field should contain a unique borrowernumber, preferably sequential. cardnumber the user's library card "number." It does not actually need to be a number. surname the user's family name firstname can actually be as many "first" names as necessary title e.g. "Mr." othernames names after the first name can be put here instead of in firstname initials the person's initials, e.g. 'John Doe' = 'JD'; rarely used and relatively unimportant streetaddress actually the mailing address; see also physstreet suburb useful in some countries city and also the state, etc., any other info needed for the mailing address other than the postal code phone the telephone number emailaddress the e-mail address faxnumber the number of the person's fax machine textmessaging contact information for any text messaging device altstreetaddress street address of the person's alternate contact (contactname) altsuburb alternate contact's suburb altcity alternate contact's city (and state/province AND postal code) altphone alternate contact's telephone number dateofbirth should be entered in MySQL format (yyyy-mm-dd), Koha will convert based on your parameters setting branchcode your code for the branch where the person enrolled categorycode your code for the type of member; 'C' is suggested for children, since this triggers some of the guarantor options dateenrolled the date when the person enrolled, in MySQL format (yyyy-mm-dd). You should set this to '0000-00-00' if you have no enrollment date. Leaving it blank (NULL) leads to inaccurate dates when editing borrower records later. gonenoaddress set to '1' if the person has moved without leaving a forwarding address lost set to '1' if the person's library card has been reported lost debarred set to '1' if the person has been "debarred" or blocked from receiving library service for excessive overdues or fines, etc. studentnumber a student ID number, but could be used for any ID number (e.g. Social Security number in the USA) school the student's school (for use with student number) contactname the name of the person's alternate contact borrowernotes any notes or messages about the person guarantor for children, this is the borrowernumber of the adult parent or custodian area a two-letter code set by the library to identify the service area in which the person resides (may be omitted) ethnicity useful for libraries that are required to track service to ethnic minorities, but easily ignored ethnotes any notes related to ethnicity sex 'M' or 'F' (male or female); 'M' is the default expiry the date when the person's membership expires, in MySQL format (yyyy-mm-dd) altnotes any notes or messages about the alternate contact altrelationship the nature of the alternate contact, can be 'workplace', 'relative','friend' or 'neighbour' streetcity goes with physstreet if the person lives in a city other than their mailing address phoneday the daytime or "work" telephone number preferredcont a one-letter code indicating the person's preferred contact method, e.g. 'E' for e-mail physstreet the actual street address, if the person has a different mailing address (e.g. post office box) homezipcode the postal code of the person's physical street address zipcode the postal code of the person's mailing address userid this is the username the person has chosen to use to gain access to their account through the OPAC password this is the password the person has chosen to use to gain access to their account through the OPAC; it cannot be plain text, but must be encrypted using MD5 (md5_base64) before importing flags these are the person's privileges, which can be set when editing their record. The privileges are stored as the decimal representation of a binary number, with each binary digit indicating whether the privilege is allowed ('1') or not allowed ('0'). Typically, you will want to give imported borrowers the privileges to borrow books and reserve books for themselves, which can be set by inserting the integer 384 in this column. The most important pieces of information are the borrowernumber and the cardnumber (required), the person's surname and firstname, their mailing address, and the branch at which they enrolled. All of the other information can be useful but may be omitted without affecting Koha's operation significantly. Probably the easiest and fastest way to load the borrower data into Koha is to use a simple Perl script or a spreadsheet utility to put the information into a comma-separated value (csv) file, with the same structure as the Koha borrowers file, and then use MySQL's LOAD DATA INFILE utility to load the data. If using a spreadsheet utility to do this, for example, you would create a spreadsheet with a column corresponding to each column in the borrowers table, put your borrower data into these columns, and save the whole thing in csv format. If you used "borrowers.csv" for the name of this file, you would then go into MySQL and do: mysql> LOAD DATA INFILE "borrowers.csv" INTO TABLE borrowers FIELDS TERMINATED BY ',' ENCLOSED BY '"'; This process is fast, loading tens of thousands of borrower records in only a couple of seconds.

Obviously, once you have loaded your bibliographic records and your borrower records, you need to know which borrowers have borrowed which items, which borrowers have reserves on which items, which borrowers owe fines for which items, etc. In other words, you need your transaction records, which relate your books to your borrowers. As with borrower records, you will have to dig out as much information as possible from your existing database, using whatever means possible. Most likely, you will have to either access your database directly and dump the data you need (if possible) or ask your current vendor to do it for you. In any case, you will probably want to retrieve the following transaction information (at least): items on loan, and to whom they are (and were) loaned; borrowers who are blocked from using the library (and why); borrowers who have bad addresses; charges owed by borrowers; items reserved by borrowers. Remember, because transaction records bascially involve some sort of relationship between borrowers and items, you want to be sure you have already loaded both your bibliographic and user records before you load transaction data. Here are the Koha database tables that store transaction data:+-------------------------+ | Transaction Tables | +-------------------------+ | accountlines | | accountoffsets | | issues | | reserves | +-------------------------+ Some of the columns in the borrowers table also hold some transaction-type data, namely gonenoaddress (set to "1" if the borrower has moved without leaving a new address), lost (set to "1" if the borrower has lost their library card), debarred (set to "1" if the borrower's library privileges have been suspended), and borrowernotes, which can hold any textual information about the borrower. The accountlines and accountoffsets tables hold information about charges which the borrower owes the library:SHOW COLUMNS FROM accountlines; +-------------------+---------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +-------------------+---------------+------+-----+---------+-------+ | borrowernumber | int(11) | | MUL | 0 | | | accountno | smallint(6) | | | 0 | | | itemnumber | int(11) | YES | | NULL | | | date | date | YES | | NULL | | | amount | decimal(28,6) | YES | | NULL | | | description | text | YES | | NULL | | | dispute | text | YES | | NULL | | | accounttype | varchar(5) | YES | | NULL | | | amountoutstanding | decimal(28,6) | YES | | NULL | | | timestamp | timestamp(14) | YES | MUL | NULL | | +-------------------+---------------+------+-----+---------+-------+ SHOW COLUMNS FROM accountoffsets; +----------------+---------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +----------------+---------------+------+-----+---------+-------+ | borrowernumber | int(11) | | | 0 | | | accountno | smallint(6) | | | 0 | | | offsetaccount | smallint(6) | | | 0 | | | offsetamount | decimal(28,6) | YES | | NULL | | | timestamp | timestamp(14) | YES | | NULL | | +----------------+---------------+------+-----+---------+-------+ For migration purposes, accountlines is the table that needs to be loaded with your existing data about charges owed by users. The accountoffsets table stores information about payments made against the account. For example, if a borrower owes the library $20.00 for a lost book, that information would get loaded into the accountlines table's borrowernumber, itemnumber, amount and amountoutstanding columns. Initially, amount and amountoutstanding are the same. If the borrower then makes a $10.00 payment toward this account, the payment amount is stored in accountoffsets.offsetamount and a new value for accountlines.amountoutstanding is calculated. Probably the most important data you want to move from your existing ILS to Koha is the record of which books each borrower has. This data gets loaded into the issues table:SHOW COLUMNS FROM issues; +-----------------+---------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +-----------------+---------------+------+-----+---------+-------+ | borrowernumber | int(11) | | MUL | 0 | | | itemnumber | int(11) | | MUL | 0 | | | date_due | date | YES | | NULL | | | branchcode | char(4) | YES | | NULL | | | issuingbranch | char(18) | YES | | NULL | | | returndate | date | YES | | NULL | | | lastreneweddate | date | YES | | NULL | | | return | char(4) | YES | | NULL | | | renewals | tinyint(4) | YES | | NULL | | | timestamp | timestamp(14) | YES | | NULL | | +-----------------+---------------+------+-----+---------+-------+ The column names in this table are mostly self-explanatory. The most important for the migration process are the borrowernumber (which, you'll remember, is not the same as the library card number), the itemnumber (not the same as the barcode number) and the date_due. If you do not know the branch where the item was issued, that's OK -- you'll still have a record of who has what and when it is due. All the dates should be loaded in the yyyy-mm-dd format expected by MySQL. The returndate column will remain empty until the item is returned. Records are not deleted from the issues table when the item is returned -- Koha knows the item has been returned by checking for a return date. Finally, you'll need to load information about reserved items into the reserves table:SHOW COLUMNS FROM reserves; +------------------+---------------+------+-----+------------+-------+ | Field | Type | Null | Key | Default | Extra | +------------------+---------------+------+-----+------------+-------+ | borrowernumber | int(11) | | | 0 | | | reservedate | date | | | 0000-00-00 | | | biblionumber | int(11) | | | 0 | | | constrainttype | char(1) | YES | | NULL | | | branchcode | varchar(4) | YES | | NULL | | | notificationdate | date | YES | | NULL | | | reminderdate | date | YES | | NULL | | | cancellationdate | date | YES | | NULL | | | reservenotes | text | YES | | NULL | | | priority | smallint(6) | YES | | NULL | | | found | char(1) | YES | | NULL | | | timestamp | timestamp(14) | YES | | NULL | | | itemnumber | int(11) | YES | | NULL | | +------------------+---------------+------+-----+------------+-------+ Again, most of the column names are self-explanatory. The constrainttype column is used to indicate whether the reserve has been placed on "any" copy (in which case the constrainttype will be "a" and the biblionumber will be set) or "one" specific copy (in which case the constrainttype will be "o" and the itemnumber will be set). The found column value is set once the item has been returned and is ready to be checked out to the borrower or to be sent to the pick-up branch (which is recorded in the branchcode column). The priority column keeps track of who is next on the list for the item. Once a reserve has been filled, the priority is set to "0."

Many of the tools you will use in the process of writing scripts and manipulating data have web documentation: MySQL the basic commands you will need to work directly with your database. Perl the programming language used for Koha. DBI the Perl database interface that allows you to include MySQL commands in your Perl scripts and retrieve data for use in scripts. CGI the Common Gateway Interface that allows Perl scripts to send data to, and retrieve data from, a webpage. MARC::Record the Perl module that allows you to manipulate MARC records. HTML::Template the Perl module that allows you to set up webpage templates to display Koha data, or modify the default templates to suit your library. Additional help is also available by sending an e-mail to the Koha mailing list.