Alma Digital : import errors and how to find them
This document presumes that you are creating new digital records by using a DCXML or MARCXML file and associated resource files, ingesting them using Alma’s Digital Uploader or by using the S3Browser API.
There are 3 main categories of errors:
1. DC field errors
You’re using a non-Alma-compliant DC/DCTERMS field
You’ve misspelled/mistyped a DC/DCTERMS field
2. Invalid XML (errors within the XML file itself)
3. Filenames non-matching
DC field errors
Why am I getting this error?
1: Not all standard DC/DCTERMS fields are enabled in Alma. Therefore you may come across an import issue even though there is nothing technically wrong with your DC fields.
2: Alma requires all DC/DCTERMS fields to have correct capitalisation (camel case for two-worded field).
For example, dcterms:accessrights will cause an error, whereas dcterms:accessRights is correct.
There is no definitive glossary of which fields are valid in Alma (and new ones are occasionally added) so the best test is to open a Dublin Core record and start typing into the field. Alma will automatically fill the field, so you can see if your preferred field is there.
How to fix it
In Resources > Import > Monitor and View imports, find the ingest that has not correctly imported.
Click on Manual Handling Required
This will take you to the Resolve Import Validation Errors page.
From there, click on the ellipsis and then View Records
This will take you to the Handle Import Validation Errors page, from which you can see what the error is, and in how many records it occurs. The example is only for a single error in a single record, but multiple errors in multiple records appear the same way.
From there click on the ellipsis under Number of Errors and click on View errors (UX note - why is this not just the button). From there you can see the entire record, including the error field/s in the right hand column.
Unfortunately there’s no way to fix the errors from this page, but at least you can see what it is. From there, you can click on the back button to go back to the Handle import Validation Errors page, and then reject the file.
You can then fix the errors and re-import.
Note: It’s important to fix incorrect or non-standard fields before import as afterwards (if you choose Force Import) fixes either have to be manual or possibly by using a Dublin Core Normalisation rule (XSL Transformer). The former is time consuming and the latter may be beyond the technical capabilities of Library staff.
What does an incorrect field look like in Alma?
If you have managed to upload a record with an incorrect field into Alma, it will appear as below. (Note: we managed to do this accidentally by using a DC Normalisation rule to change data from one field to another. The takeaway here is to double check spelling in fields, as Alma uses US English and some common words are different in British English, e.g. licence/license).
In the View Record view, the field appears:
However, when you open the record to edit, the following message appears:
When you click OK and the record loads, the field is blank and an alert appears in the Alert tab.
The invalid field exists in the XML (Tools > Dublin Core > XML View) so could possibly be fixed by an XSLT, but much easier to do so beforehand.
Invalid XML
What’s gone wrong?
Your XML file has an error in it, rendering it ‘invalid’ ie it cannot be read by Alma.
How to fix it
When your XML file is invalid, you’ll get a Completed With Errors message in the Monitor and View Imports page:
There’s no more information to be had, apart from how many files processed and rejected (zero in this example).
From there, your best bet is to run your XML through a validator. This is particularly useful for librarians who have never encountered XML before as it’s very easy to miss small errors. 3rd party software such as Notepad ++ colour codes its fields to indicate errors and also automatically validates upon saving, although these validation errors may not always point to where the actual error is. Free XML validating websites such as https://www.xmlvalidation.com/ can be very useful as well.
Note: XML validators may get confused by MARCXML and not recognise the schema.
Filenames non matching
What’s gone wrong?
This is a subset of the above problem, but can occur more frequently because file names often need to be entered manually when creating/editing the records in your text editor or spreadsheet.
The filename content in the 856$u or dc:identifier field is not an exact match with the filename, including spaces. That is, if the filename is Casablanca.mp4, then the field must be
<dc:identifier>Casablanca.mp4</dc:identifier>
NOT
<dc:identifier>Casablanca.mp4 </dc:identifier>
The same goes for MARCXML in the 856 $u field.
Click on the ellipsis and then View file details
From there we can see that Alma divided our original file of 91 records into 2 files of 46 and 45 records. One of those processed and the other did not, because it has non-matching data in the 856 $u field.
Note: files upload quicker if there are no spaces in the file name. For example, chapter_1.pdf will upload more quickly than chapter 1.pdf. The difference is enough that it’s worth the time spent taking out the spaces, especially with Alma’s 60min time outs.