Koha Migration Process

things to doThe available documentation from the Koha community has a very useful implementation checklist that libraries should consider when thinking about and planning the migration process. The checklist includes steps for the following topics:

Data Migration:

  • Create a list of libraries and enter their information and codes.
  • Define your list of item types.
  • Define your patron categories and enter the categories and their codes.
  • Enter any additional patron information fields you use in your library.
  • Define all of your authorized values.
  • Optionally define city/postal code combinations and road types for patron entry.
  • Map your bibliographic data from your legacy system to Koha fields and migrate (remember to use the collection, shelving, item type, and library codes you entered in the above setting areas).
  • Map your patron data from your legacy system to the Koha fields and migrate (remembering to use the patron and library codes you defined above).
  • Test your migrated data to be sure that everything is as you expect it to be.

Administrative Configuration:

  • If your library uses CAS authentication, you'll want to set the various CAS system preferences.
  • Set the administration system preferences.
  • Go through the log system preferences and decide which actions you want to keep track of in the logs.

Localization Configuration:

  • Decide how dates are displayed throughout Koha.
  • Decide if patrons can choose what language the OPAC appears in.
  • Decide which languages the patrons can choose from.
  • Decide which languages appear in the staff client.

Circulation Configuration:

  • Define your circulation/fine rules.
  • Enter the days your library is closed for fines and due date calculations.
  • Enter circulation system preferences.
  • Customize your notices.
  • Define your overdue notice triggers.
  • Set up your cron jobs.

Patron Configuration:

  • Enter your staff members as patrons.
  • Define patron system preferences.

Cataloging Configuration:

  • Define your cataloging templates aka MARC bibliographic frameworks.
  • Define any authorized values you might want to use in cataloging.
  • Set up custom classification sources (if you use something other than the defaults).
  • Set up MARC matching rules for importing records from MARC files or Z39.50.
  • Set up Koha to keyword mapping for deciding how to display MARC fields to the screen.
  • Set up the Z39.50 targets you want to search for cataloging (and acquisitions).
  • Define cataloging system preferences.
  • Set up your cron jobs.

Authorities Configuration:

  • Set authority frameworks aka templates.
  • Set authority system preferences.
  • Set up your cron jobs.

Searching Configuration:

  • Set up your cron jobs.
  • Define searching system preferences.

OPAC Configuration:

  • Decide how you want your OPAC to look and what content you want on the main page.
  • Create a library branded stylesheet using CSS.
  • Create a custom XSLT stylesheet to change the way search results and bibliographic records appear in the OPAC.
  • Define OPAC system preferences.
  • Set up your cron jobs.

Enhanced Content Configuration:

  • FRBR/Editions
  • Amazon
  • Babeltheque
  • Baker and Taylor
  • Google
  • LibraryThing
  • Novelist
  • OCLC
  • Syndetics
  • Tagging

Acquisitions Configuration:

  • Set up your funds and budgets.
  • Choose your default currency and enter others if you order from multiple countries.
  • Enter in your vendor information.
  • Create a framework with the code ACQ (if you're going to enter item records at the time of ordering or receiving).
  • Define acquisitions system preferences.

Serials Configuration:

  • Define serials system preferences.
  • Define cataloging system preferences.

Planning for Go-Live:

  • Decide if you need training by an outside service or if your staff can do the training themselves.
  • Make sure that there is time for your staff to play with your test system and get comfortable with it.
  • If this is a migration, work with your previous company to extract data right before you go live.
  • Come up with URLs for your new Koha OPAC and staff client.
  • Make sure that if you are hosting your own system you have a backup plan.

Also consider consulting case studies about other libraries' process of migrating to Koha, including the Electronic Information for Libraries page and this Slideshare presentation.

Best Practices for Migration
  • Spot check data (during testing, migration, and after migration). Catching problems early means less work trying to fix problems later.
  • Write workflows and policies/rules beforehand. Writing these during based on the test site should provide step by step instructions on how to do the final migration.
  • If working with a vendor, regular communication is important. Having regular meetings ensures that everyone stays on the same page and prevents miscommunications that will slow down the process. Having one person as liaison between the library and the vendor will ensure a clear chain of communication.

Demo Sites

Demo sites serve many functions. They can be used in evaluation. They provide the opportunity to do data mapping (see Data Preparation). Demo sites can be used to determine and test what the best setup (rules, policies, settings, etc.) is for your library. and for staff to learn the system. Staff training should be conducted using the demo site by providing the opportunity to learn the different modules and how they differ from your library's current ILS. These differences should be documented by creating new workflows. Lastly, they serve as a test run for migration.

Koha vendor Liblime provides demo sites with which to try the Koha staff interface and OPAC: http://www.liblime.com/demos.

The Koha Community wiki lists several demo sites: http://wiki.koha-community.org/wiki/Koha_Demo_Databases


In general, Koha is going to be most appropriate for small libraries.  Koha has been especially popular with small public libraries and school libraries.

The next step is to create a list of the necessary features of your current ILS. This is a great opportunity to include the whole library staff. Have each department (Circulation, Acquisitions, Cataloguing) create the list for their department. Compare this to the current version of Koha. If you can show your staff that Koha has the same features as your current ILS, it should reassure them. If you can show them that Koha has more features than your current ILS, they should became more supportive. If there are things on your list that are not currently available in Koha then you have three options: 1) wait until it comes available, 2) decide that you can live without it and migrate anyway, or 3) develop it working with a vendor, in partnership with another library or by yourselves.

At some point early in the process, it will be necessary to create a migration team. These are the people who will actually carry out the migration. There are several ways to choose this team. A couple of points to keep in mind, the more excited and open to OSS ILS the members are the more likely they are to do a good job. While having technical skills makes the process easier (so if you have people with those skills definitely include them), it is more important to have people who will seek out answers and are willing to learn the needed skills. If you are going to work with a vendor, designate a liaison between the migration team and the vendor. That way there is a clear line of communication and the vendor doesn't have multiple people asking them the same questions. 

Best Practices for Evaluation
  • Make a list of requirements and don't migrate until they are all there.
  • Know your staff's abilities before committing.
  • Talk to other libraries.
  • Include as many people as you can in the decision to move to open source.

Koha Data Preparation

Unless you are automating a library for the first time, you will have data from an existing system that will need to be moved to the new Koha installation. This is one of the most important steps in the migration process, and managing the data preparation process is a key step to a successful migration. Data preparation is often talked about as data "mapping," meaning to ensure that the data fields between the two systems match up properly.

According to the Koha community documentation, there are two types of data mapping: that of bibliographic data and that of patron data. Mapping bibliographic data involves mapping and matching MARC records. Dealing with patron information, in contrast, requires creating a patron file and importing patrons.

Koha has the advantage of being a fairly new system, designed from the ground up to handle MARC records, while many legacy systems may not use MARC at all as the basis for their bibliographic data. Systems also vary in the types of items they allow and the way these are coded. All of these values must be mapped to the Koha system and checked to make sure that the record is accurate and useable.

Best Practices for Data Preparation
  • If you can do a fine amnesty when migrating. Sometimes it is very difficult to transfer fine data into a new ILS so an amnesty will make the process simpler.
  • Clean up data in advance. The more consistent your data is the easier it will be to transfer. in addition, migrating to a new system is a chance for a fresh start. It is an opportunity to clean up any inconsistencies in the old system.
  • Weeding - as part of your data clean up you should consider doing a weeding process on both materials and patron records. The fewer records you have the faster migration will be. If you are planning on using a vendor, they charge by record so why pay for records you don't need?
  • Consistency is key. If multiple people are working on the data make sure they are working based on the same standards.

Koha Customization

Koha is highly customizable with a variety of enhancements available. The following are just a few examples:

During Migration:

  • Create scripts to aid in the transition from a proprietary ILS to Koha.
  • Simulate patrons checking in and returning books to test Koha installations.
  • Perform simple modifications to MARC records before importing into Koha.


  • Customize the staff client with CSS.
  • Add a toolbar of Koha-related items to Firefox browsers.
  • Use Firefox to continue circulation offline.
  • Generate customized reports, such as statistics and late notices (and custom print these).

OPAC Appearance:

  • Add the library name in the browser's top bar.
  • Insert an image or text into the header area.
  • Change the masthead color to match the header image.
  • Change or hide the masthead image.
  • Add text/links/images into the lefthand sidebar.
  • Add text/links/images into the main part of the front page.
  • Add a customized footer.
  • Make various stylesheet changes (color, font, size, etc.).
  • Change wording or hide certain areas.
  • Change the appearance of cart and list buttons.
  • Show item type limits on the checkout screen.
  • Customize additional search options.

Consult the following websites to begin researching more information: Koha-Tools Collection of Enhancements, Koha Wiki CSS Customizations, LibLime's OPAC Customizations, and the Koha Blog's aggregation of posts related to customization. Also visit the Koha Wiki for a list of library websites with customized OPACs.

Best Practices for Customization and Development
  • Before doing any customization make sure it hasn't or isn't in the process of being done. The great thing about open source is that any development done by any library comes back to the community, so often if you want something done someone else does too.
  • Look for partnerships. Usually others in the community want the same things as you. The advantage in partnerships is the combination of resources be that monetary or staff skills.
  • Consider grants as a funding option.

Koha Training Resources

In addition to consulting documentation from Koha and LibLime, individual libraries usually develop training resources for their own staff and patrons about their particular OPAC. Examples of topics to include are training videos, patron training, circulation, cataloging, reports, going live, and updates. The Northeast Kansas Library System's training materials provide a good example that other libraries may want to follow.

Best Practices for Staff Training
  • Documentation is important. The best way is to find what documentation is already available and then customize it for your system.
  • Usually a day or two of training is sufficient. Since training covers circulation, cataloging and administration most staff members will only need to be there for their part of it.
  • Do training fairly close to Go Live date. Two reasons for this: first is that if training is done close to the Go Live date then they can be trained on the actual system they will use. Second, if training is done too early often people either don't take it seriously or forget what they learn before the Go Live date.
  • When training have specific tasks to do. There are several ways to do this. 1) Do the specific tasks at the training. 2) Demonstrate the tasks at training and then give 'homework' where the staff does the specific tasks independently. 3) Have staff try the tasks on their own and use the training session for questions or problems they had. For options 2 and 3, staff have to have access to a demo system.


Going live with Koha

Congratulations, you have made it to the last step!

A couple of words of advice. If possible, keep your old ILS running for a couple of months just in case you need to use it for reference. Sometimes it takes a little while to make sure that EVERYTHING migrated correctly. Run some tests to make sure that everything is working correctly.

If possible, you may want to close your library for a half-day or more to make sure that staff are fully trained on how to use it. If you've done a lot of advertising to patrons about your new system and OPAC it may run slowly at first due to heavy access as people try it out, so be prepared for delays. Expect some calls from patrons who are surprised by the new interface and need help adjusting.