Koha Migration Readiness Checker

A successful Koha migration is not simply a matter of exporting records from one system and importing them into another. Bibliographic records, item holdings, patrons, current circulation, local codes, matching rules, authorised values, identifiers and operational cutover decisions all interact. A migration can appear almost finished while one unresolved issue — such as incorrect branch codes, duplicate patron identifiers, an untested MARC matching rule or no verified rollback path — still makes a production cutover unsafe.

The VWS Online Koha Migration Readiness Checker is designed to make those gaps visible. Instead of treating every checkbox as equal, it assesses only the data types you select, groups controls into weighted readiness domains and separately identifies critical blockers. The result is a practical planning audit: a percentage helps summarize progress, but critical incomplete controls can still produce a Not ready for production migration verdict.

What the Koha Migration Readiness Checker evaluates

The revised checker covers the parts of a Koha migration that normally require evidence before cutover: project scope, target Koha configuration, bibliographic and MARC quality, item and holdings mapping, patron data, active operational transactions, additional modules, testing and reconciliation, and cutover/recovery planning.

You first choose the data that is actually in scope. A catalog-only migration should not lose points because patrons are not being migrated. A full operational migration, however, should include the relevant patron, checkout, hold, account and module-specific controls. The checker then shows only the applicable evidence questions.

Migration scope: assess only what you are moving

Koha projects vary widely. Some institutions are loading a new catalog into an otherwise configured Koha installation. Others are replacing a legacy ILS and need to migrate catalog records, item holdings, patrons, active checkouts, holds, balances, authorities, acquisitions and serials.

The checker lets you select:

• Bibliographic records
• Items and holdings
• Patrons
• Current checkouts
• Holds or requests
• Fines or account balances
• Authority records
• Acquisitions
• Serials

Core project, configuration, testing and cutover controls remain relevant to every migration. Domain weights are normalized across the active scope so the score remains understandable without penalizing genuinely excluded data.

How the readiness score works

Each visible control can be marked Complete, Partial, Not started, Unknown or Not applicable. Complete earns full credit, Partial earns half credit, and Not started or Unknown earns no readiness credit. Not applicable controls are removed from that domain's denominator.

This scoring is deliberately transparent. It is not an official Koha score and does not predict whether an import will succeed. It is a VWS planning heuristic that helps teams see which migration areas have evidence and which still depend on assumptions.

More importantly, the percentage does not override critical blockers. If a representative MARC import has never been staged, patron match identifiers contain unresolved duplicates, active loans have no tested cutover strategy, or backups and rollback have not been proven, the checker can keep the migration in a not-ready state even when many lower-risk controls are complete.

Project and scope readiness

Migration work becomes difficult to reconcile when the source export is not repeatable or the team has not agreed what is being migrated. The Project & Scope domain therefore asks whether the source systems and export methods are documented, migration scope and exclusions are explicit, baseline record counts have been captured, reviewers have been assigned and a data-freeze or final-delta strategy exists.

Baseline counts should be captured by data type rather than as one vague total. For example, record the expected number of bibliographic records, items, patrons, active checkouts and holds separately. Those values become the reference point when a pilot or final migration is reconciled.

Target Koha configuration must exist before the data can fit

A technically valid source value can still fail in Koha if the target configuration does not contain the corresponding code. Library or branch codes, item types, patron categories, shelving locations, collection codes, authorised values and MARC framework mappings should therefore be prepared before the production load.

The checker treats several configuration gaps as critical when their data is in scope. If imported item records contain branch or item-type codes that do not exist in the target, the problem should be resolved in the crosswalk or target configuration rather than discovered during the final import.

Koha permissions and relevant system preferences also matter. Staff need the correct import permissions, while staging, matching and overlay behavior should be understood before records are committed to the catalog.

Bibliographic and MARC migration readiness

Koha can import MARC and MARCXML records, but production readiness involves more than having a file with a .mrc extension. The source MARC flavor should be known, character encoding should be verified, structural errors should be triaged and identifier/matching behavior should be decided.

The official Koha cataloging and record-import documentation describes record import as a staged workflow. Records are first staged into the reservoir, where Koha can report the number of records, MARC errors, matches and staged items. The staged batch is then reviewed and imported. This makes a representative staging pilot a natural readiness gate rather than an optional last-minute test.

If you have not yet reviewed the MARC structure, use the MARC21 Validator. For spreadsheet review or cleanup, the MARC to Excel Converter can expose bibliographic and Koha 952 data in tabular form. When the cleaned source data starts in Excel, the Excel to MARC Converter for Koha Libraries can help prepare reviewable MARC output.

Record matching rules need evidence, not assumptions

A migration that loads records into an existing Koha catalog needs a clear duplicate and overlay strategy. Koha record matching rules use match points, scores and a threshold to determine whether an incoming record matches an existing one. The current Koha administration documentation explains that the combined match score must meet the configured threshold and that required match checks can be used alongside match points.

See the official Koha administration manual for current matching-rule behavior. Do not assume that a rule that sounds correct — for example ISBN matching — behaves acceptably on your source records without testing representative duplicates, missing identifiers and edge cases.

The readiness checker therefore treats a tested matching rule, a decided overlay/add/ignore policy and a reviewed staged MARC batch as high-impact controls.

Koha item and holdings migration: focus on MARC21 952

For MARC21 Koha installations, item data is commonly represented in field 952. Important examples include:

• 952$a — home library
• 952$b — holding library
• 952$d — date acquired
• 952$g — purchase price
• 952$o — item call number
• 952$p — barcode
• 952$t — copy number
• 952$y — item type

The current Koha item database schema documentation maps these values into the items table. A readiness review should therefore verify not only that a 952 field exists, but that branch codes, item types, identifiers, status values, dates and prices match the target Koha configuration and local policy.

Item barcodes deserve particular attention because they are used heavily in circulation and can also participate in item matching during imports. If you need to establish a controlled new range, use the Koha Barcode Generator. If the identifiers already exist and you only need printable labels, use the Library Barcode Sheet Generator.

Patron migration readiness

Patron imports combine data quality with privacy risk. A source CSV can contain names, addresses, email addresses, phone numbers, identifiers, dates of birth, category values, home-library codes, account dates, notes and custom attributes. Only the data that is needed and authorized should be included in migration files.

The official Koha Tools manual documents the patron import workflow, including CSV-based imports and matching on fields such as card number or username to prevent duplicates. Unique patron attributes can also be configured as match points in appropriate installations.

The checker asks whether mandatory patron fields have been identified, branch and category values match the target, match identifiers have been checked for duplicates, dates and UTF-8 text have been normalized, extended attributes/restrictions are handled, and privacy-sensitive fields have been reviewed.

An Unknown answer is intentionally visible as risk. Saying “we do not know whether card numbers are unique” is materially different from having verified that they are unique.

Current checkouts, holds and balances require operational decisions

Moving static catalog data and moving live operational state are different projects. Current checkouts have borrowers, items, checkout dates and due dates. Holds contain queues, pickup information and record/item relationships. Account balances require an agreed financial definition and reconciliation.

If these areas are selected, the checker asks for a tested strategy rather than assuming that they can be imported using the same process as MARC records. Source counts and totals should be captured before cutover so the target can be reconciled after migration.

The Koha SQL Reports Generator can help create reviewable read-only reports for current Koha data quality and reconciliation where appropriate.

Authority, acquisitions and serials migrations

Authority records have their own record type and matching considerations. Acquisitions contain vendors, funds, budgets, order state and financial relationships. Serials can contain subscriptions, numbering patterns, claims and routing information. These should not be treated as anonymous extra columns in a catalog spreadsheet.

When those modules are selected, the readiness checker adds module-specific planning controls and asks whether local custom fields, plugins or source-only data have an explicit keep, transform or retire decision.

Testing and reconciliation are production gates

A pilot migration should contain realistic data, including difficult records, not only a small clean sample chosen because it is easy to import. The revised checker treats the following as production-critical evidence:

• A representative dataset containing normal and edge cases
• An end-to-end pilot in a test or non-production Koha environment
• Source-to-target count and total reconciliation
• Manual verification of representative records in the Koha interface and reports

Record counts alone are not enough. A migration can have the correct number of items while every holding branch is wrong. Manual spot checks complement aggregate reconciliation by confirming that mappings produce sensible real records.

Known errors should be logged with owners and an explicit decision. Some issues may be acceptable exceptions; others may require a transformation or another pilot. The important point is that they should be understood before cutover.

Cutover, backup and rollback planning

A production migration needs a controlled point of no return. Final source exports or backups should be complete, protected and restorable. The team should know how a rollback would work, who can authorize it and at what point the migration should be stopped rather than continued.

The final-delta plan also matters. If cataloging or circulation continues after the main export, those changes need a defined path into Koha or the source system needs a controlled freeze. Downtime communication, staff availability and immediate post-launch checks should be scheduled rather than improvised during the cutover window.

Why critical blockers override the percentage

Traditional checklist scoring can create false confidence because every checked item adds the same amount of progress. In this checker, missing staff training is not treated as identical to an untested rollback procedure, and a documented barcode convention cannot compensate for an untested patron deduplication rule.

A high weighted percentage therefore means that a large share of the applicable readiness evidence is complete. It does not mean that the migration is safe to launch if critical blockers remain.

Use owners, evidence and notes

Each readiness control can store an owner and a short evidence note in the browser form. Useful evidence is specific. Instead of writing “barcodes checked,” write something like “86,419 item rows checked; zero duplicate non-empty barcodes; 17 missing values assigned to remediation ticket MIG-42.”

Evidence makes the assessment easier to review in meetings and easier to repeat after a new data extract. It also reduces the chance that a status was marked Complete based only on memory.

Export a migration action plan

After assessment, the tool shows domain scores, the overall weighted readiness score, critical blockers and high-risk gaps. You can download a UTF-8 CSV containing every applicable control, status, critical flag, owner and evidence note. You can also copy the blocker/action list or use the browser print function to save the result as PDF.

This export is intended as a planning artifact, not as proof that Koha has independently validated the source data. Keep it with your migration change log, mapping documents, pilot results and reconciliation reports.

A practical VWS Koha migration workflow

1. Define the migration scope and capture baseline counts.
2. Configure target branch codes, item types, patron categories, authorised values and frameworks.
3. Validate MARC structure with the MARC21 Validator.
4. Use MARC to Excel when tabular cleanup or auditing is helpful.
5. Prepare reviewed MARC output with the Excel to MARC Converter when your source starts in spreadsheets.
6. Test matching rules and stage a representative MARC batch in Koha.
7. Reconcile item, patron and operational identifiers before the final load.
8. Run the readiness checker again and resolve every critical blocker.
9. Complete the controlled cutover, then reconcile the final target counts and manually inspect representative records.

Common Koha migration mistakes

Scoring progress instead of assessing risk

A project can be 90 percent complete and still have one unresolved issue that makes launch unsafe. Use the blocker list, not only the percentage.

Testing MARC syntax but not matching behavior

A structurally valid MARC file can still create duplicates or overwrite the wrong records if matching and overlay rules are wrong.

Assuming source codes will work in Koha

Branch, item-type, patron-category and authorised-value codes should be deliberately crosswalked to the target configuration.

Ignoring unknowns

If nobody knows whether patron IDs are unique or whether a location code exists in Koha, treat that uncertainty as work to resolve rather than silent completion.

Running one clean pilot

A useful pilot includes messy and unusual records. It should test the failure paths you expect to encounter in the real migration.

No final-delta strategy

If the source remains active after the primary export, new changes can be lost unless there is a freeze or a documented delta process.

Frequently asked questions about Koha migration readiness

Is the readiness score an official Koha certification?

No. It is a transparent VWS planning heuristic based on the applicable controls you mark. It helps organize evidence and gaps but does not replace testing in your own Koha environment.

Why can a migration score highly and still be marked not ready?

Some gaps are production blockers. An untested pilot, unresolved matching rule, invalid target codes, duplicate patron identifiers or missing rollback evidence can outweigh completion of many lower-risk tasks.

Do I need to complete patron checks for a catalog-only migration?

No. Select only the data types in scope. Patron and operational domains are excluded from scoring when those data are not being migrated.

Why is staging a MARC batch considered important?

Koha's staging workflow shows record counts, MARC errors, matches and staged items before the batch is finally imported. A representative staging run provides direct evidence about how your source behaves in the target.

What should I check for Koha 952 item data?

At minimum, verify the source-to-952 mapping, branch codes, item types, barcodes, call numbers, status values and relevant dates/prices. Local authorised values must match the target Koha configuration.

What should I check before importing patrons?

Confirm required fields, branch/category codes, chosen matching identifiers, duplicate card numbers or usernames, dates, UTF-8 text, extended attributes and the privacy need for each field being migrated.

Does this tool upload my migration data to Koha or VWS Online?

The readiness assessment records statuses, owners and notes in the browser interface and does not connect to your Koha database. Avoid placing confidential patron records or passwords in evidence notes; use counts, ticket references or sanitized evidence instead.

What should I do after all critical blockers are complete?

Review remaining high risks, obtain local approvals, run the final reconciliation plan, confirm backups and rollback, and perform a controlled cutover with post-launch validation. A clean blocker list is a gate for review, not an automatic command to launch.

Related Koha migration tools

Use the MARC21 Validator for record structure, the MARC to Excel Converter for tabular inspection, the Excel to MARC Converter for reviewed spreadsheet-to-MARC workflows, the Koha SQL Reports Generator for reconciliation and data-quality reporting, the Koha Barcode Generator for controlled new item identifiers, the Library Accession Number Generator for accession sequences and the Book Spine Label Generator for call-number label preparation.

A good migration is repeatable, reviewable and reversible. Use the checker to expose assumptions early, then support every Complete status with evidence from the source data, a representative Koha pilot or a documented operational decision.