Catalog import

The catalog importer is how a batch of records gets into Lyra’s catalog. It accepts MARC and spreadsheets, processes each record in the background, and sorts the results into review buckets you can act on. This page covers running one.

The file formats themselves — accepted extensions, the three spreadsheet templates column by column, the MARC fields and holdings conventions Lyra maps, and how rows group into items and copies — are in Catalog import formats.

For the patron-side equivalent, see Roster import.

What the catalog importer is

A single import that brings in items and their copies. One import carries as many files as you have, in either source format, in any combination:

MARC — the default output of most cataloging tools and the usual path when migrating from another ILS. Files end in .mrc or .marc.
Spreadsheet — a simpler tabular path for libraries without MARC, or starting from a vendor report, including a shelf list exported from your old system. It comes in three templates — books by ISBN, books by title and author, and everything else — and Lyra works out which one each file is from its column headings. Each file may be an Excel workbook (.xlsx or the older .xls) or a .csv. A workbook with a sheet per item type counts as several files: each sheet is read on its own, against the template its own columns matched.

There is no rule against mixing them: a MARC export of the book collection and a spreadsheet of the equipment go in together, and so do four spreadsheets that are all the same shelf list report. Every file goes up to 50 MB.

Starter templates

Building a spreadsheet from scratch rather than exporting one? Start here.

item-import-templates.xlsxEvery catalog template, one sheet each. Fill in what you need — a blank sheet is ignored.

Or one template at a time, as a CSV:

The column-by-column contract for each is in Catalog import formats.

Either way, the importer reads records into Lyra’s item-and-copy model, groups records that describe the same item, and fetches covers in the background.

Getting to the importer

Go to navigation path: Catalog then Imports from the sidebar. Importing is a library-manager action — other staff can view imports but won’t see the way in at all.

Once the page lists imports, the header’s button: Import file button opens the import dialog. Drop in whichever files you have and Lyra reads each one, listing them with what it will read each as: a MARC file is named as MARC, and a spreadsheet gets the template its column headings matched, which you can correct before anything runs. A workbook with several sheets is listed a sheet at a time, each named beside the file it came out of, and each correctable on its own. A spreadsheet whose columns Lyra wants you to confirm says message: Columns to map on its row; see Mapping a spreadsheet’s columns. A file Lyra cannot read at all says so on the spot, and the rest of the files are unaffected.

If every book in the import is identified by title, the dialog says what that costs: those records import exactly as written, with no cover, topics, description or edition, because the books-by-title template has no columns for them. Adding an isbn column to the file fills all four from ISBNdb, and so does a MARC export. The note does not appear when the import already carries a books-by-ISBN file or a MARC file, because those records get them either way.

While the library has no imports at all, the page shows a panel headed card: Import items into your catalog. instead of a table: a drop target that takes the same files, and links to the migration guides and this page. Files dropped there, or picked with its button: Choose files button, open the same dialog, already holding them. The header carries no button on that panel — the drop target is the way in, and it is library-manager-only for the same reason the header button is, so other staff see the panel without it. The first import replaces the panel with the table for good.

Any drop target in Lyra says whether it will take what you are dragging. If it can tell from the file alone that it will not — a PDF, a Word document, an image — the target turns red while the file is over it, your pointer shows the “no drop” cursor, and letting go does nothing. It cannot always tell: a MARC export carries no file type your computer recognizes, so the target stays neutral and reads the file once you drop it. A file that gets that far and still can’t be imported is listed with what it is (“Lyra can’t read a .txt file”) rather than silently ignored. Either way the way in through button: Choose files is unaffected.

Mapping a spreadsheet’s columns

A spreadsheet imports without this step only when every column heading in it is one of Lyra’s own column names for the template it’s read as, and it has that template’s identifying column: isbn for Books by ISBN, title for the other two. A filled-in starter template qualifies, and so does a file Lyra exported. Every other spreadsheet says message: Columns to map on its row, including a Destiny or Alexandria report whose headings Lyra already recognizes, so you see what Lyra decided before thousands of rows act on it. In a workbook, each sheet is mapped on its own. MARC files are never mapped.

When you select the dialog’s import button, Lyra opens a dialog: Map Columns step for each spreadsheet still to map, one after another, with a count such as message: 1 of 3 to map above the file name. button: Next moves on to the next file. On the last one the button is the import button again, and selecting it starts the import. button: Back returns you to the file list without importing, and keeps the mappings you already confirmed.

To map a file before you import, select button: Map columns on its row. That opens the step for that file alone, and button: Done takes you back to the list. The row then says message: Columns mapped, with button: Edit to reopen it.

The step lists each column in your file with its first value as a sample, and a menu beside it for the Lyra column it holds. Lyra fills these in for you: first the headings it recognizes (the Recognized headings in Catalog import formats), then headings whose words are close to a Lyra column’s name, such as Book Title for Title. Anything it can’t place starts as setting: Don't import, and a column left that way isn’t imported. Check each row, and change the ones Lyra got wrong.

Each Lyra column goes to one file column. Pick a Lyra column another column already has, and it moves. The column it left says so, for example message: Barcode moved to Item Barcode.
The template’s column is required. Until the file has one, a line above the table says what’s missing, such as message: Books by ISBN needs an ISBN column., and the button stays unavailable.
field: Reading as changes the template. Every template is offered. Lyra keeps the choices that still fit the new template and guesses the rest again.

Changing what a file’s row is read as, back in the list, clears the mapping you confirmed for it, since a mapping is made against one template’s columns. Mappings aren’t saved between imports: the next file from the same system starts from Lyra’s guesses again.

Add to catalog, or stage for review

Every import makes you pick an field: Import mode before it runs:

setting: Add to catalog — records that parse cleanly with no issues go straight into the catalog. Only records that need attention (a missing title, an unreadable ISBN, a missing barcode, or a duplicate barcode) wait for you on the import’s detail page. A clean record whose ISBN already exists in this library isn’t held back — its copies are added to the existing item automatically. This is the fast path when you trust the file.
setting: Stage for review — nothing is added to the catalog automatically. Every record is staged for review — clean ones in the import’s tab: Ready to add bucket, anything with a problem in tab: Issues — so you can review the whole batch first, then add the records you want. It’s a dry run you commit in place: review, then button: Add to library.

Both modes produce the same detail page, the same tabs, and the same per-record actions. The only difference is where clean records start: in tab: Added copies (Add to catalog) or in tab: Ready to add (Stage for review). A staged import opens on tab: Ready to add, holding everything the run validated.

Imports are queued

Import processing is asynchronous. Uploading only queues the import; all the work — parsing, validation, the ISBN lookups, and writing records — happens afterward in a background worker. An import moves through status: Processing → status: Complete (or status: Failed), and its status is shown on the detail page and in the imports list. A complete import that still has records waiting on you reads status: Needs review instead, with a count of how many are left to review.

This means:

You don’t wait at the upload screen. As soon as the files are uploaded and queued, Lyra closes the dialog and leaves you on the imports list, where the new import is listed with its status — moving you there if you started somewhere else, and staying put if you were already on it. Its status updates as the worker gets through the file, and you’re free to navigate away.
Records land as the worker processes them. A large import takes time; records are written in batches, and the catalog is usable as they land.
You get an email when it’s done. When the import finishes, Lyra emails whoever started it — whether it completed or failed. The email summarizes the outcome (how many items were added, staged for review, or skipped) and includes a button that opens the import’s detail page, so you can jump straight to the results without hunting for the import in the list.
A status: Failed import keeps whatever landed before it stopped. Open it from the imports list, or from the email, to see exactly what that was — the tab: Added copies and tab: Ready to add tabs list it the same way they do for a completed import. The page leads with a banner saying the import didn’t finish, the files it carried are above it so you can download them again, and underneath is a panel offering the three ways on: button: Ask Vega about this file, button: Read the import troubleshooting guide, and button: Email support, which opens a message already carrying the import’s id and the page you were on. On the tab: Skipped tab the same three sit on each record instead — point at or tap its reason. Fixing the file and importing it again is safe: Lyra checks every barcode in the file against the ones already in your library, so records that made it in the first time come back as status: Duplicate barcodes issues to review rather than as second copies, and records that didn’t are matched to the items the first run created instead of making new ones.

What the importer fetches during the run

As it works through the file, the background importer also:

Looks up covers by ISBN. Records are processed in batches, and for each batch Lyra does one bulk cover lookup against its book-data provider, keyed on ISBN. Only records that have an ISBN and don’t already carry an image are looked up — so a record that supplied its own image_url, or a MARC 856 cover link, keeps that image, and non-book items (which have no ISBN) get no automatic cover. When no cover is found, the item simply has none and shows a placeholder icon in the staff app and OPAC.
Queues search indexing. Once the import finishes, its items are queued for search indexing — Lyra digests each item’s title, authors, topics, and description for AI-powered search in the OPAC. In an account whose owner has turned semantic search off, nothing is sent, and the items are indexed once it’s back on.

A books by ISBN import leans on the same book-data provider one step earlier: before inserting, the importer does a bulk lookup of every ISBN in the file and fills in title, authors, description, cover, topics, and edition fields. The Books by ISBN columns list exactly which fields it fills and which it leaves alone. A books by title import does none of this — it has no ISBN to look anything up by, so the item is exactly what the file said, and covers and topics stay empty until you add them.

Working an import

Once an import is status: Complete, open it from navigation path: Catalog then Imports to work its results — each row in that list is headed by the date and time it was uploaded, which is also the link into it, with a row action: View on the row itself and the file names beside the date as supporting detail. (Importing and resolving records are library-manager actions. Other staff can open a completed import and download labels from its tab: Added copies and tab: Ready to add tabs, but the resolve actions — edit, ignore, add to library, and assign missing barcodes — stay manager-only.)

The detail page is titled by when the import ran — Import Sep 2, 1:42 PM, because the same items.csv uploaded every week would otherwise give you three pages with one name — and carries a status badge, a strip of four counts, and a tab for each count: tab: Added copies, tab: Ready to add, tab: Issues, and tab: Ignored. A stage-for-review import opens with a banner reminding you nothing has been added yet.

Under the title is a card: Files strip listing the file (or files) the import was created from — which is where the file names live, beside the control that downloads each one. Each one is a button: select it to download the original upload, byte for byte, under the name you uploaded it with. That’s the copy to open when a whole column parsed wrong and fixing records one at a time isn’t the answer — correct the spreadsheet or MARC file and import it again. Any staff member can download an import’s source files; you don’t need to be a library manager.

Every parsed record lands in one bucket — one tab, each a searchable table. Import outcomes defines each bucket and the three issue flags; what follows is what to do in each one.

The four record tabs carry an button: Item Type column — Book or Other, set by the template each file was read as — and the same field as a pinned button: Item type filter, so a mixed upload (a MARC shelf list beside a sheet of equipment) can be worked one type at a time. Narrowing by it narrows the tab’s button: Download menu and select all matching with it, so labels, exports and the bulk resolve actions cover exactly the rows on screen.

tab: Added copies and tab: Ready to add also carry a button: Barcode column, and a button: Call Number and button: Location column you can switch on under button: Columns. A record on tab: Ready to add is not yet a copy, so where one covers several copies — each with its own barcode — the cell counts them instead, and a call number or location its copies disagree on reads Mixed. Open the record to see them one by one.

tab: Added copies — records that are now in your catalog. In an Add to catalog import they went straight in; in a setting: Stage for review import this starts empty. From here you can download barcode and spine labels for the batch.
tab: Ready to add — clean records waiting for you to commit. Every clean record in a stage-for-review import starts here; in an add-to-catalog import the tab fills as you resolve records from tab: Issues. A row’s row action: Add to library commits that one; select rows and button: Add to library to move them to tab: Added copies, or button: Ignore to set them aside. To add or ignore the whole tab at once, check the header box and take Select all matching; Lyra asks you to confirm before it acts on every record the filters match. You can also download barcode and spine labels for these drafts before they’re added.
tab: Issues — records that couldn’t be added automatically, each flagged status: Missing title, status: Unreadable ISBN, status: Missing barcodes, or status: Duplicate barcodes. Those flags are the record’s state, not buttons — repairing it is what the row is there for, so row action: Edit sits on the row itself; menu item: Ignore and menu item: Assign barcode stay in the row’s menu item: ⋯ menu.

The dialog: Fix Record dialog opens with what is wrong stated above the fields: the record’s source row, a flag for each issue, and one line per issue saying what to do about it. An

status: Unreadable ISBN names the isbn cell Lyra couldn’t read, so you can fix it in the file or type the right ISBN here; a status: Duplicate barcodes names the barcode that is already in use. Where a fix is one press — every copy missing a barcode — button: Assign barcodes sits in that banner and fills the fields, so you can see what it chose before you commit. The lines disappear as you fix them.

Below the banner the dialog shows the whole record, with summary, topics, reading level and audience folded under button: More details — open it when you want them, or when the file already carried values for them. The copy fields offer the same call number suggestions as the add flows, prefilling only when no copy on the record already has one.

Finish with button: Add to library, or

button: Save without adding — saving is separate from adding, so a half-finished fix isn’t lost. Either one, and button: Ignore this record, moves you straight to the next record in the tab; button: Previous and button: Next in the dialog’s header step through them by hand, with your place shown between the two. That means a file with thirty broken records is thirty presses, not thirty round trips through the table.

Two common fixes: point the record at an existing item in the library instead of creating a new one (when it’s really another copy of something you already have), or select barcode-less rows and

button: Assign missing barcodes to assign fresh, unused ones. To do it for every record the filters match, select all matching first. If none of the selected records is missing a barcode, the band says so. A resolved record moves to tab: Ready to add.
tab: Ignored — records you’ve set aside. row action: Un-ignore returns one to tab: Ready to add or tab: Issues, wherever it belongs. Select rows and choose button: Un-ignore to return several; with all matching selected, Lyra confirms first.
tab: Skipped — records the importer couldn’t read at all: a malformed MARC record, a CSV row with the wrong number of fields, or a spreadsheet row with values in columns the header row never named. Skipped records never enter the catalog, and the tab (with a matching banner) appears only when there are any. It’s read-only: each row shows the row or record the file carried it on and why it couldn’t be read, plus a button: File column naming which of the upload’s files it came from — that column appears only when the import carried more than one, since otherwise every row would name the same file.

button: Download ▸ menu item: Skipped records pulls the records back out to repair in your cataloging tool or spreadsheet and re-import. When every skipped record came from one file you get that file on its own — a skipped-records.mrc from a MARC file, a skipped-records.csv from a spreadsheet. When they span several, you get skipped-records.zip holding one file per source file, named after it (skipped-shelf-list.csv, skipped-catalog.mrc), each in its own format so it opens in the tool that wrote it.

A whole file that couldn’t be read gets one row here too, carrying its header line and the reason. That is what a file dropped into the wrong slot looks like once it has been uploaded; see Catalog import formats.