Best Practices for Migrating from Proprietary and Legacy ILS Platforms to Koha Open Source LMS

For many libraries, the moment arrives when the familiar, however creaky, must give way to the possible. Decades of cataloging, circulation history, patron records, acquisitions, and serials sit buried in a legacy or proprietary Integrated Library System (ILS) that few people fully understand anymore. Somewhere in that database is a MARC field last touched during the Windows XP era, still haunting librarians like an archaeological relic from the CD-ROM revolution.

Yet a migration to Koha, the world’s most widely deployed open-source library management system, is not only achievable; done right, it becomes a transformation. Libraries emerge with cleaner databases, faster catalogs, more empowered staff, and complete ownership of their data. The journey simply demands planning, patience, and the right practices.

This guide amalgamates real-world migration experience, Koha community wisdom, and insights from leading migration specialists. Whether you are moving from a proprietary ILS, a government-legacy system, or an older Koha installation, what follows is your comprehensive, practical, and honest roadmap.

Why Libraries Are Choosing Koha

Before diving into the how, it is worth revisiting the why. Libraries across the world, academic, public, school, and special, are increasingly adopting Koha because it offers a fundamentally different relationship between a library and its software:

• No vendor lock-in, your bibliographic data belongs to your institution, not a software company.
• Zero licensing fees, budget freed for collections, staff, and services.
• Full MARC21/UNIMARC standards compliance, interoperability out of the box.
• Community-driven development, thousands of libraries worldwide continuously improve the platform.
• Web-based, modern architecture, accessible from any device, anywhere.
• Powerful integrations, RFID, discovery layers, LDAP/SSO, Z39.50, and more.
• Complete customization, workflows, notices, reports, and OPAC tailored to your library’s identity.

A Note on Open Source: Unlike proprietary environments where information is sometimes guarded like classified intelligence, the Koha ecosystem thrives on shared learning and collaborative improvement. The Koha Community Manual, mailing lists, and global forums are freely available to every library, regardless of size or budget.

Migration Is Not Just a Technical Process

One of the most dangerous misconceptions about library data migration is that it is simply “copying data” from one system to another. It is not. A migration is simultaneously:

• A data quality project, exposing inconsistencies accumulated over years of informal practice.
• A metadata standardization exercise, normalizing MARC fields, indicators, and authority records.
• A workflow redesign opportunity, questioning every inherited habit and convention.
• A systems integration process, connecting Koha to institutional directories, payment gateways, and discovery layers.
• A staff training challenge, empowering your team before they ever touch the new interface.
• A long-term preservation responsibility, ensuring institutional knowledge survives the transition.

A poorly planned migration carries old mistakes permanently into the new system. A well-planned migration dramatically improves catalogue consistency, search quality, circulation efficiency, and reporting capability. The difference lies entirely in preparation.

Phase 1: Pre-Migration Audit, Know Your Data

No migration should begin without a thorough audit of the existing system. You cannot plan a journey without first knowing exactly what you are moving.

What to Inventory

• Bibliographic records, total count, formats, encoding, and quality level.
• Item/holding records, barcodes, item types, locations, statuses (lost, withdrawn, on order).
• Patron records, active vs. inactive, categories, and contact completeness.
• Circulation data, active loans, holds, reservations, and due dates.
• Financial data, outstanding fines, payment histories, and waived amounts.
• Serials, subscription records, routing lists, issue histories.
• Acquisitions, pending orders, vendor accounts, and fund structures.
• Administrative data, staff accounts, branch configurations, notice templates.
• Authority records, name authorities, and subject heading vocabularies.
• Custom fields and local MARC practices, unofficial field repurposing, and local tags.

Legacy systems frequently contain years of informal practices. Critical information may live in notes fields because someone did it once in 2011, and everyone continued. Migration is the perfect moment to surface such irregularities.

💡  Pro Tip Involve a cross-functional team from the start: a project lead, a data specialist or senior cataloguer, a systems administrator, and a representative frontline staff member. Early involvement accelerates decisions and dramatically reduces rework.

Phase 2: Clean Your Data, Garbage In, Garbage Out

The most repeated advice from every migration expert, community forum, and support provider is consistent and unambiguous: clean your data before you ever touch the new system. Computers are astonishingly efficient at preserving human mistakes forever.

Bibliographic Records

Begin with your MARC records, since they form the backbone of your catalog. Check for:

• Invalid or missing MARC tags and incorrect indicators.
• Duplicate bibliographic entries, these create phantom holdings and confuse patrons.
• Broken character encoding is especially critical for Indian language scripts, Arabic, or any non-ASCII content.
• Non-standard subject headings or authority mismatches.
• Missing ISBNs, ISSNs, or control numbers.
• Empty mandatory fields (titles, authors, publication years).

Use MARCEdit, a free, industry-standard tool, to validate, edit, and transform MARC records in bulk. It is invaluable for mass corrections before import.

Patron Records

Clean patron data protects privacy, improves notifications, and prevents authentication issues.

• Remove expired patrons with no outstanding balances or active loans.
• Eliminate duplicate user accounts, typically created when patrons register multiple times.
• Normalize phone numbers, email formats, and address fields to consistent patterns.
• Standardize patron categories, reduce to a clean, logical set that maps clearly to Koha borrower categories.
• Plan your password migration strategy: legacy proprietary systems encrypt passwords using hashes Koha cannot read. Prepare a password-reset workflow (e.g., first login prompts reset, or defaults to barcode/date of birth).

Item Records

• Verify global barcode uniqueness; even a single duplicate causes major circulation problems.
• Standardize item types, shelving location codes, and collection codes.
• Resolve ambiguous item statuses, lost, missing, withdrawn, and on order, should each map to a clear Koha status.
• Verify consistency of call number formats (Dewey Decimal, LC, Accession Number, etc.).

⚠️  Common Pitfall Do not attempt to migrate serials and acquisitions data without specific review. Serials records, in particular, often require manual handling, subscription states, issue patterns, and routing lists rarely map cleanly from proprietary formats.

Phase 3: Configure Koha Before You Import a Single Record

A common and costly mistake is to import data into Koha before the system is properly configured. If item types or location codes in the imported data do not match the authorised values in Koha, the result is a catalogue full of unmapped, broken records.

Configure these foundations before migration begins:

• Libraries and branches: define all branch codes (short, alphanumeric, no spaces or special characters).
• Item types (itype): create a clean, consolidated set of item type codes.
• Patron categories: match these to the normalized categories from your data cleanup.
• Authorized values: shelving locations (LOC), collection codes (CCODE), lost/damaged/withdrawn statuses.
• Extended Patron Attributes: if your library uses custom patron fields (e.g., Department, Roll Number for academic libraries).
• Circulation rules: configure loan periods, renewal limits, fine rates, and grace periods per item type and patron category.
• MARC bibliographic frameworks: Customize fields visible to cataloguers.
• System preferences: especially IndependentBranches, item-level_itypes, and AutoCommit.

💡  Pro Tip If your legacy system uses numeric codes (e.g., location code “14” for Reference Section), provide descriptive labels during configuration. This is the moment to give your codes meaningful, human-readable names.

Phase 4: Data Mapping – Build the Blueprint

Data mapping is the intellectual core of any migration. It is the process of explicitly documenting how each field in your legacy system maps to Koha’s data structure. Without a complete, reviewed mapping document, troubleshooting later becomes an exercise in guesswork and regret.

The Master Field Mapping Table

The table below provides a starting framework. Your specific migration will require a detailed version covering every field in your legacy system:

Legacy System Element	Koha Equivalent	Key Notes
Bibliographic Record	MARC21 Bib Record	Export as MARC21; use MARCEdit to fix/validate
Copy / Item Record	Item Record (952 tag)	Map all subfields carefully (see 952 guide)
User / Patron Account	Koha Patron	Normalize patron categories; plan password reset
Loan Rules / Policies	Circulation & Fine Rules	Configure in Koha before importing any data
Branch / Sub-Library	Library/Branch Code	Short alphanumeric codes (≤10 chars, no spaces)
Collection Type	Item Type (itype)	Consolidate where possible; keep codes simple
Shelving Location	LOC Authorized Value	Use consistent codes across all branches
Overdue Fine	Fine Structure in Koha	Map fine amounts and grace periods explicitly
Barcode	Item Barcode (952$p)	Ensure global uniqueness across all copies
Call Number	Call Number (952$o)	Verify format: Dewey, LC, Accession, etc.

The Power of the MARC 952 Tag

One of the most important concepts for anyone migrating to Koha is understanding how it handles item (holdings) data. Unlike some proprietary systems that store holdings in separate, isolated tables, Koha binds item data directly into the bibliographic MARC record using the 952 tag. Every item attached to a bibliographic record must have a correctly populated 952 field.

Here are the critical 952 subfields you must map for every item:

Subfield	Meaning	Example Value
952$a	Home Library (branch code)	MAIN, SCI, LAW
952$b	Holding Library	MAIN (same as $a unless floating)
952$c	Shelving Location (LOC)	REF, STACK, CHILD
952$o	Full Call Number	629.13 / ACC-2024-001
952$p	Barcode	T001234, 2024-08-001
952$y	Koha Item Type (itype)	BK, DVD, JRNL, THESIS
952$7	Not for Loan status	0=available, -1=ordered
952$z	Public Note (visible in OPAC)	Gift of Dr. Sharma, 2019

💡  Pro Tip Use MARCEdit’s “Add/Edit Field” function to bulk-populate 952 subfields from your exported item data. This is one of the most time-saving steps in the entire migration process.

Code Standardization Rules

When creating codes for item types, location, collection, and patron categories, follow these rules to prevent ongoing headaches:

• Keep codes short, 10 characters maximum, ideally 3–6 characters.
• Use alphanumeric characters only, no spaces, hyphens, or special characters.
• Be consistent in case, uppercase is conventional (e.g., BK, DVD, JRNL, THESIS).
• Create a translation matrix, document every legacy code and its Koha equivalent before import.

Phase 5: Technical Preparation for Large-Scale Imports

For libraries with large collections (typically over 10,000 records), a few server-side optimizations will make the import process significantly smoother.

Database Configuration (MySQL/MariaDB)

Large bibliographic imports can fail if database packet limits are too low. Before importing, temporarily adjust:

• max_allowed_packet, increase to 256M or 512M in your MySQL configuration file.
• innodb_buffer_pool_size, increase to improve import throughput.

Use Command-Line Import Tools

For large-scale imports, the command-line tools are faster, more reliable, and free from browser timeout limitations:

• bulkmarcimport.pl, Koha’s primary tool for bulk bibliographic import.
• misc/migration_tools/bulkmarcimport.pl -d -file /path/to/records.mrc for full import.
• koha-rebuild-zebra -b -i -v, rebuild the search index after every significant import.

Encoding Enforcement

Ensure all exported data from your legacy system is strictly converted to UTF-8 encoding before import. Legacy systems often contain corrupted characters or diacritics that appear normal in the old system but break Koha’s indexing. This is especially critical for:

• Indian language scripts (Devanagari, Gurmukhi, Tamil, Telugu, Malayalam, etc.)
• Arabic, Persian, and Urdu records.
• Records with French, German, or Spanish diacritics.

💡  Pro Tip MARCEdit’s built-in character encoding conversion tool can detect and fix encoding issues before import. Run it on every MARC file before loading into Koha.

Phase 6: Test Migrations, Iterate, Don’t Shortcut

Never perform a production migration without multiple test imports on a dedicated staging server. This is the most important and most frequently skipped step in library migrations. Experienced migration teams perform at least two to three complete trial runs before final cutover.

The Test Migration Sequence

1. Pilot Import: Import a small, representative sample of each record type, perhaps 500 bibliographic records, 1,000 items, 200 patrons. Validate everything before proceeding.
2. Bulk Test Import: Import a larger, statistically significant batch, ideally 10–20% of total records. Run extensive search and circulation tests.
3. Full Test Migration: Import the complete dataset. This is your dress rehearsal. Document every issue found. Fix, and repeat if necessary.
4. Final Production Migration: Only when the full test migration passes all validation checks.

What to Test in Each Iteration

• Record counts: compare source counts vs. imported counts for every data type.
• OPAC display: check bibliographic records, especially those with diacritics, series information, or non-Latin scripts.
• Search functionality: test keyword, author, title, subject, and ISBN searches.
• Circulation workflows: check out, check in, renew, place holds, return.
• Fine generation: confirm fine rates are calculating correctly against imported loan data.
• Patron logins: test patron authentication across categories.
• Reports: run standard statistical reports and verify expected outputs.
• Serials display: confirm subscriptions are visible in OPAC and staff interface.

The test phase often reveals hidden surprises. Somewhere in the database, there is always a patron account named “TEST”, created in 2009, still holding 47 overdue books and somehow immune to deletion. Better to find it in testing than after go-live.

⚠️  Common Pitfall Allocate at least 30% of your entire migration timeline to testing. It feels like a large commitment, but it is far less painful than scrambling to fix critical issues after your library has already gone live.

Phase 7: Go-Live, Managing the Transition

The final cutover from the legacy system to live Koha is a carefully choreographed sequence of events. The primary challenge is the “delta”, the gap between your last test export and the moment Koha goes live, during which your library continues to operate.

The Freeze Period Strategy

• Choose a low-activity window, semester breaks, weekends, or public holidays.
• Put the legacy system into read-only mode, so staff can look up records but cannot catalog new items or modify patron accounts.
• Maintain an offline circulation log, Koha’s built-in Offline Circulation Tool (available as a browser extension or CSV template) lets staff record barcodes and patron IDs offline during the freeze window.
• Perform the final export, extract the freshest possible snapshot of active loans, holds, and any last-minute changes.
• Import the final data batch, follow your tested import sequence exactly.
• Rebuild the search index, run koha-rebuild-zebra -b -i -v and confirm search is functioning.
• Open the doors, announce go-live to staff and patrons.

Rollback Planning

Always enter go-live with a tested rollback plan. Know exactly how long rollback would take and who has authority to call it. Keep the legacy system accessible in read-only mode for at least 30–60 days after go-live as a reference backup.

Communicating with Patrons

Communicate planned downtime clearly and in advance, through the OPAC, email, social media, and physical signage. Patrons are generally understanding when they are informed. They become significantly less understanding when they discover the system is down while standing at the circulation desk holding a stack of books.

Common Pitfalls, and How to Avoid Them

1. Insufficient Testing

The single most common cause of migration problems. Testing is not optional, and one round is rarely enough. Test early, test often, and test with real staff using real scenarios.

2. Incomplete Data Mapping

Discovering unmapped or incorrectly mapped fields mid-migration forces costly delays. Invest the time upfront in a thorough, reviewed, signed-off mapping document.

3. Ignoring the Koha System Preferences

Koha is immensely configurable. Forgetting to set preferences like IndependentBranches, AutoCommit, or item-level_itypes can make perfectly migrated data behave in confusing and unexpected ways.

4. No Rollback Plan

Migrations can fail. Maintain a parallel system, have verified backups, and ensure a rollback procedure exists and has been tested before cutover.

5. Underestimating Data Cleanup

Libraries consistently underestimate how much manual cleanup their legacy data requires. Build cleanup time should be generously built into your project timeline; it is almost always the longest phase.

6. Recreating Every Legacy Customization

Resist the temptation to replicate every quirk of the old system inside Koha. Ask instead: Is this customization still necessary? Does Koha already offer a better workflow? Migration is an opportunity to modernize, not merely to transplant old inefficiencies into a new environment.

7. Poor Staff Communication

A technically flawless migration can still feel like a failure if staff were not involved, trained, or informed. Keep your team in the loop at every stage.

Staff Training: The Human Side of Migration

A new system is only as effective as the people using it. Training must begin well before go-live, using the test environment with real migrated data.

Training Should Cover

• Cataloging workflows: adding, editing, and merging bibliographic records.
• Circulation operations: checkout, checkin, renewals, holds management.
• Patron management: adding, editing, and merging patron accounts.
• Report generation: built-in Koha reports and the SQL report library.
• Acquisitions: creating orders, receiving items, managing budgets.
• Serials management: subscription setup, issue prediction, and claiming.
• OPAC administration: customizing the public catalog interface.

Create department-specific quick-reference guides, printed checklists for the circulation desk, and a troubleshooting FAQ for the first weeks after go-live. The investment in documentation pays dividends for years.

The Master Migration Checklist

Use this checklist as a framework for your migration project. Adapt it to your library’s specific context and size.

Pre-Migration
☐	Complete inventory: bib count, item count, patron count, loan count
☐	Identify and resolve duplicate bibliographic records
☐	Remove expired patrons (no outstanding balances)
☐	Standardize item types, location codes, patron categories
☐	Validate barcode uniqueness across all items
☐	Export sample MARC files and review with MARCEdit
☐	Plan password reset strategy for patron accounts
☐	Take full backup of legacy system (DB + MARC exports + CSV)
Koha Setup
☐	Define libraries/branches with short alphanumeric codes
☐	Create all item types, patron categories, authorized values
☐	Configure circulation rules, fine structures, and loan policies
☐	Set up MARC bibliographic frameworks
☐	Configure system preferences (IndependentBranches, item-level_itypes, etc.)
☐	Test Zebra/Elasticsearch indexing with sample records
Test Migration
☐	Run pilot import: small sample of each record type
☐	Validate OPAC display, search results, diacritics, and special characters
☐	Test checkout, checkin, holds, renewals, and fine generation
☐	Compare source vs. target record counts
☐	Involve frontline staff in workflow testing
☐	Iterate: fix issues, re-import, re-validate
Go-Live
☐	Freeze legacy system (read-only mode)
☐	Export final delta: active loans, holds, last circulation transactions
☐	Import final data batch into live Koha
☐	Rebuild Zebra/Elasticsearch index (koha-rebuild-zebra -b -i -v)
☐	Run post-import validation and reconciliation counts
☐	Keep legacy system accessible in read-only mode as a reference
☐	Communicate go-live to patrons
Post-Migration
☐	Monitor system for 30–90 days; watch for anomalies
☐	Schedule a formal post-migration audit
☐	Schedule formal post-migration audit
☐	Gather staff feedback and resolve lingering mapping issues
☐	Tune system preferences and report templates
☐	Document lessons learned for future reference

Post-Migration: The Work Is Not Over

Go-live is not the finish line. The first 30 to 90 days after cutover are a critical stabilization period. Libraries should expect and budget for a period of fine-tuning.

• Monitor Koha continuously: watch for search anomalies, circulation errors, and patron login failures.
• Listen to staff feedback: Frontline staff is your best source of real-world data quality issues.
• Run integrity checks: compare record counts, verify item statuses, and audit circulation data weekly.
• Schedule a formal post-migration audit at 30–90 days, document all issues found and fixes applied.
• Leverage Koha features you could not use in the old system, such as custom reports, label printing, patron self-registration, and SMS notifications.
• Keep the legacy system in read-only mode for reference; do not decommission it until you are fully confident in the migrated data.

Final Thoughts

Migrating from a proprietary or legacy library system to Koha is both a technical and organizational transformation. Its success depends far less on the sophistication of import tools and far more on preparation, data quality, rigorous testing, honest communication, and staff involvement.

Libraries that approach migration thoughtfully consistently emerge with cleaner bibliographic databases, better patron management, improved discovery experiences, more efficient workflows, greater institutional control over their data, and significantly reduced long-term operational costs.

Most importantly, migration to Koha represents a philosophical shift, toward openness, toward interoperability, toward community-driven innovation, and toward a future where your library’s data truly belongs to your library.

Start with your data. Clean it with care. Map it with precision. Test it without mercy. Then open the doors, and welcome your library to its open-source future.

Useful Resources

• Will-power
• Koha Community Manual, koha-community.org/manual
• ByWater Solutions Migration Guides, bywatersolutions.com/education
• KohaSupport Migration Playbook, kohasupport.com/knowledge-base
• MARCEdit (free MARC editing tool), marcedit.reeset.net
• Koha Mailing Lists & Forums, lists.koha-community.org