How to Test a Koha Migration with a Small MARC Sample

A Koha migration should not begin with the full catalogue import. Start with a small, representative sample.

A good test sample helps you find problems early: malformed MARC, missing items, duplicate records, branch mapping errors, item type problems, encoding issues, and OPAC display concerns.

This article explains how to choose and test a small MARC sample before a full migration.

Why a small sample matters

A sample import is faster, safer, and easier to review.

It helps answer:

• Can Koha stage the file?
• Do records import correctly?
• Are items created?
• Are barcodes present?
• Do branches and item types map correctly?
• Does search work?
• Do titles and authors display properly?
• Are accented characters preserved?
• Are duplicate rules working?

If the sample fails, the full import will probably fail too.

What to include in the sample

Do not choose only the cleanest records. A useful sample should include normal records and difficult records.

Include:

• common books;
• older records;
• records with accents;
• records with multiple ISBNs;
• records without ISBNs;
• records with several copies;
• records from different branches;
• records with withdrawn or lost statuses;
• records with local notes;
• records from different material types;
• vendor records if they will be part of the migration.

A 25–100 record sample is often enough for an initial test.

Step 1: Keep the original export

Never edit the only copy of your export. Keep:

• original export from the legacy system;
• cleaned or repaired working copy;
• MARCReady output if used;
• import notes;
• mapping decisions.

Good migration documentation saves time later.

Step 2: Review the sample in MARCReady

Upload the sample to MARCReady.

Check:

• invalid indicators;
• ISBN formatting;
• empty subfields;
• duplicate fields;
• character encoding problems;
• Leader and 008 warnings;
• field mapping if the source is CSV, Excel, TSV, or JSON.

Review the repair log to identify the problems most likely to affect import.

Step 3: Export a repaired sample

After reviewing, export a small MARC21 or MARCXML file.

Do not process the full catalogue until the sample behaves correctly in Koha.

Step 4: Stage the file in Koha

In Koha, use the staged import workflow.

Review:

• record count;
• staging warnings;
• failed records;
• matches found;
• item count;
• import profile;
• matching rule;
• item handling settings.

If the staged counts are not what you expect, stop and investigate.

Step 5: Import into a test catalogue

Use a test Koha environment where possible. Avoid using a live production catalogue for early migration tests.

After import, check:

• staff record view;
• OPAC record view;
• title search;
• author search;
• ISBN search;
• subject search;
• barcode lookup;
• branch display;
• item availability;
• call number display.

Step 6: Document what needs to change

Create a short migration notes file.

Record:

• source file name;
• MARCReady warnings;
• mapping changes;
• Koha staging settings;
• matching rule used;
• item handling choices;
• issues found;
• changes needed before the next test.

Step 7: Repeat before full import

Migration testing is iterative. A first test often reveals mapping or data issues.

Repeat the sample process until:

• records stage without unexpected errors;
• imported records display correctly;
• item data is present;
• duplicate handling works;
• staff can find records;
• OPAC display is acceptable.

When to ask for help

Ask for help if:

• Koha reports many staging errors;
• item data does not import;
• branches or item types do not map;
• duplicate handling is unclear;
• records contain complex local fields;
• source data is only available in spreadsheets;
• the migration affects a live library.

KohaSupport can advise on migration planning and MARC preparation.

Related articles

• How to Validate MARC Records Before Importing into Koha
• Koha Stage MARC Records for Import: Settings Explained
• MARCReady — Supported File Formats