Koha to Alma Data Delivery Specification
Migration Overview
The procedure for migrating from the Koha Library System to Ex Libris’ Alma consists of the following steps:
- Indicate which local fields correspond to Ex Libris' expected fields using the Koha Field Mapping Form prior to data delivery (customer responsibility).
- Validate the flat files using the Non-ExLibris to Alma Validation Tool. It is recommended that this step be done against a small sub-set of data to ensure that the header of each of your flat files and the filled in field mapping form match each other.
- Extract the relevant data elements from Koha into flat files (customer responsibility).
- Upload the files to Ex Libris’ secure file server (MFT) along with the Koha Delivered Files List and the executed/validated Non-ExLibris to Alma Validation Tool (customer responsibility).
- Transform the data elements, based on the Generic Field Mapping Form, into an intermediate conversion XML format (Ex Libris responsibility).
- Load the transformed data into Alma (Ex Libris responsibility).
Deliver the Koha Field Mapping Form and validated data validation output to Ex Libris along with the Koha Migration Form prior to the actual delivery of the data. The lead time depends on your project schedule. Provide the Koha Delivered Files List, which lists the file names and the record counts for each file, at the same time that you provide your data extract files.
For all files, the maximum file size is 2GB. Customer should remove any stray line breaks in their extracted file, such as line breaks that might be present in note fields.
Provide the Koha data elements in flat files, and place them on an Ex Libris secure file server. Prepare the data files with the naming conventions as described in Appendix – File Delivery and Form.
DO NOT OPEN/UPDATE any delimited file extracts that you provide to Ex Libris in Excel. This may ruin the appropriate delimiter formatting and text formatting and may result in corrupted data.
Requested Files from Koha
Ex Libris expects a certain set of files to be exported from Koha. The general expected file deliveries are listed below. The data elements listed for each are those that Ex Libris expects to use in conversion. Some data elements may exist in Koha but are not necessary to bring to Alma.
The scope of your specific conversion is agreed upon in your Alma contract.
As you extract data from any area below, provide it to Ex Libris via a secure file server (MFT) connection. This facilitates the transformation analysis and expedites the conversion process. Information on the MFT connection is provided by Ex Libris. For more information, see Appendix – File Delivery and Form.
Inventory
There are two kinds of inventory files that that Ex Libris expects to receive from Koha:
- Bibliographic records with embedded items – Bibliographic records are expected in MARC format. The item records associated with each bibliographic record are expected in a tag in each bibliographic record.
- Electronic Resources (E-Resources) – Most non-Alma ILS systems store records for both physical and electronic items in the same format, which is a physical format. Alma has different record formats for electronic and physical items. Provide a list of bibliographic records that represent electronic materials so they can be converted to electronic format after migration to Alma. The possible types of electronic resources are packages, databases, and portfolios.
Fulfillment
Ex Libris does not expect to receive fulfillment files from Koha customers. If your library wants to provide fulfillment files such as patrons, loans, requests, or fines/fees, contact your Ex Libris project manager.
Acquisitions
Ex Libris does not expect to receive acquisitions files from Koha customers. If your library wants to provide acquisitions files such as vendors or orders, contact your Ex Libris project manager.
Expected File Formats
Bibliographic/item are expected in MARC format, and the p2e file is expected in CSV format with one record per line.
Koha Field Mapping Form
Prior to submitting your extracted files, complete the Koha Field Mapping Form. Indicate which data elements (files) you plan to provide in the Overview tab of the spreadsheet. On the subsequent tabs, indicate your local Koha field names and how they map to our expected field names.
Even when the name of the field provided is the same as that listed in the ExL Expected field name, the Local field name column for the fields being provided must still be filled in.
In addition, there are various note fields for each data element. For fields that are not expected by Ex Libris – meaning, there is no functional place for the data element in the corresponding Alma data structure – place the field in a note in the record. Specify which note type you want the field to go to at the bottom of each tab in the Koha Field Mapping Form.
Koha Delivered Files Form
At the time you submit the requested data files, submit the completed Koha Delivered Files List. List the files, record counts, and encoding for each file delivered to the MFT secure file server.
Inventory
Bibliographic Records
Bibliographic records are expected in MARC format. Standard MARC is preferred, but files in MARCXML format are also acceptable. The character encoding expected from Koha is UTF-8 or MARC8. Deliver all files with the same character encoding.
If you use standard 7XX fields for linking between bibliographic records, this is leveraged during migration. If the relationships are based on your bibliographic record system numbers, provide the field that contains these system numbers in the migration form.
If you have loaded SFX MARCIt records into Koha, it is recommended that they not be included in the bibliographic record export to avoid unnecessary duplication with records loaded directly from SFX. If you want Ex Libris to detect and not migrate the SFX records, ensure that a 035 |a field with (SFX) in the field content is provided, so that the records can be identified, and answer No to the question about SFX bibliographic record on the Questionnaire tab of the Koha Migration Form.
Suppressed Records
If you are able to determine which bibliographic records are in the catalog but are not shown to the public (suppressed records), provide a separate text file containing the bibliographic record number for each suppressed record, one record number per line.
Holding records
Holding records are required in Alma. Migration can get holding records from any of the following places, including a combination of the following:
a) MARC holdings exported directly from Koha
b) serial holdings records delivered in textual format, which migration converts to MARC holding format
c) generate MARC holdings based on a tag embedded in the bib (like an 866 summary statement)
d) all items require a holding, so if an item does not get attached to one of the above holding records or if no holding record was provided, then a MARC holding will be generated based on information in the item record. See the Migration Form, Questionnaire tab question 852_subfields_for_hol for more information on how a holding record is generated from an item and how an item might attach to one of the above holdings.
Non-MARC Serial Holdings
If non-MARC serial holdings (subscriptions) are provided, they should be sent as a CSV file. Records should be provide one record per line, with quotes and commas. Provide a header at the top.
| Expected Field Name | Repeat-able? | Notes |
|---|---|---|
| biblionumber | N | |
| callnumber | N | call number can be sent in multiple parts if there is an $h and $i. Send the two parts separated by semicolons, like: "PN345";".B867" |
| location | N | use as Location in Alma Location map |
| branchcode | N | use as Library in Alma Location map |
| receivedlist | Y | is placed in 866 of newly-created holding record |
Other fields from the subscription can be placed in a note in the holding record. The note can be public (852 $z) or non-public (852 $x).
Holdings From a Bib Tag
If there is summary statement information in a field embedded in the bibliographic record, the migration programs can generate a holdings record from it. Fill in the values of the following fields in the Holdings tab of the Koha Field Mapping Form. If the SUMM_LIB_CODE and SUMM_LOC_CODE match an existing holdings record on the same bibliographic record, even a holdings record that was generated from items attached to the same holdings record, the summary holdings statement is attached to that holdings record, regardless of call number. In other words, the summary holding is placed on the holdings record with the same library and location, even if 852_SUBFIELDS_FOR_HOL contains call number subfields for matching like bchi. If there is no existing holdings record on the bibliographic record with the same location, a new holdings record is generated.
| Expected Field Name | Value | Notes |
|---|---|---|
| SUMM_TAG | Five characters; tag+2 indicators. May use # as wildcard, for example, 866## | |
| SUMM_SUBFIELDS | Multiple subfields allowed, e.g. abz. May use # to indicate all subfields. | |
| SUMM_CALLNO | Textual call number to be used in all newly generated holdings records if desired. | |
| SUMM_LIB_SUBF | A single subfield code (like 'a') which contains a library code in local ILS format. Do NOT enter a different bib tag. The migration program searches for a subfield within the SUMM_TAG bib tag. | |
| SUMM_LOC_SUBF | A single subfield code (like 'a') which contains a location code in local ILS format. Do NOT enter a different bib tag. The migration program searches for a subfield within the SUMM_TAG bib tag. | |
| SUMM_LIB_CODE | If SUMM_LIB_SUBF is not provided or the subfield is not found, this is used for all records as a default. Provide a library code in local ILS format. | |
| SUMM_LOC_CODE | If SUMM_LOC_SUBF is not provided or the subfield is not found, this is used for all records as a default. Provide a location code in local ILS format. | |
| SUMM_PUBLIC_NOTE_SUBF | The public note, placed in 852 $z of the generated holding record. | |
| SUMM_NON_PUBLIC_NOTE_SUBF | The non-public note, placed in 852 $x of the generated holding record. |
Items/Holdings
Item information is expected to be provided as an embedded bibliographic record tag. Indicate which tag contains the item on the Embedded Items tab of the Koha Field Mapping Form.
The following table lists the expected subfields for item migration. If your item subfields have different contents, indicate the subfield mapping in the Embedded Items tab of the Koha Field Mapping Form. Also, indicate on the same tab which tag contains the item record, such as 949.
The maps that are indicated in the Notes column below are found in the Koha Migration Form. See the Koha to Alma Migration Guide for instructions on how to complete this form.
| Expected Field Name | Expected Subfield | Notes |
|---|---|---|
| Withdrawn status | $0 | Use in item base status |
| Lost status | $1 | Use in item base status |
| Classification | $2 | Use in Shelving Scheme map |
| Materials specified | $3 | |
| Damaged status | $4 | Use in item base status |
| Collection code | $8 | Use in location map |
| Item key | $9 | |
| Holding library | $b | Use in location map |
| Date acquired | $d | |
| purchased price | $g | |
| Serial enumeration | $h | |
| total checkouts | $l | To see this value in Alma, search for the item under 'Physical Items' and on the results list click 'Other details'. |
| Call number | $o | |
| Barcode | $p | |
| Last Loan Date | $s | To see this value in Alma, search for the item under 'Physical Items' and on the results list click 'Other details'. |
| Copy number | $t | |
| replacement price | $v | |
| Price effective from | $w | |
| Item type | $y | Use in item type map |
| Temporary library | $f | use in location map |
| Temporary location | $i | use in location map |
| Material Type | $j | use in item material map |
Any additional subfields not listed above may be put into notes. The possible note fields in Alma items are listed in the following chart in the Note Name column. The subfields listed in the Default Local Subfield column are those that are expected by Ex Libris. If you use other field names or have subfields that you want to include in the migration, but are not expected by Ex Libris, you can rearrange, add, or subtract fields in the Default Local Subfield column as necessary. The text in the Note Label column is used as a prefix to the subfield contents and can be modified, as desired. If you want to include multiple local fields in the same Alma note, copy the line in the spreadsheet as many times as needed for all note name/local field combinations.
| Note Name | Default Local Subfield | Note Label |
|---|---|---|
| PUBLIC NOTE | $z | Public Note |
| FULFILMENT_NOTE | ||
| FULFILMENT_NOTE | ||
| NON_PUBLIC_NOTE_1 | $x | Nonpublic Note |
| NON_PUBLIC_NOTE_2 | $c | shelving location |
| NON_PUBLIC_NOTE_3 | $a | owning library |
Secondary Item File
You may want to provide item descriptive information in a secondary file. For example, you have a description in the format Vol. 12 No. 2 (2015 January), but Alma recommends that enumeration and chronology information are without labels and are in separate fields. You can provide your description in a secondary item file.
Provide the secondary item file in csv format, with the following fields:
| Expected Field Name | Notes |
|---|---|
| itemKey | Provide either itemKey or itemBarcode, but not both. If both are provided, itemKey is preferred. |
| itemBarcode | |
| itemDescription | Provide in a format such as: Vol. 12, No. 6 (February 2015). |
| EnumA | For example, “12”. |
| EnumB | For example, "6". |
| EnumC | |
| EnumD | |
| EnumE | |
| EnumF | |
| EnumG | |
| EnumH | |
| ChronI | For example, "2015". |
| ChronJ | For example, "2". |
| ChronK | |
| ChronL | |
| ChronM |
Electronic Identification (P2E)
Provide a list of Koha bibliographic system numbers that represent electronic resources and an indication if these electronic resources are portfolios, packages, or database resources. The list should be a comma separated text file containing lines that represent each e-resource. The format of each line is as follows: <bibnumber>, <resource type>.
For example:
000000001,Portfolio
000000002,DB
During the P2E process, all resources must either be categorized as a portfolio or a database (DB). It is not possible to generate packages during P2E processing, since packages require at least one portfolio. A database is essentially a zero-title package. Post migration, when you add portfolios to the db, you can change them to type 'package'.
The words portfolio and db are not case-sensitive; therefore, both portfolio and Portfolio are acceptable.
Fulfillment (Patrons and Circulation)
Patrons
Extract all patrons.
All patron primary identifiers MUST be unique across all users, as required by Alma. If they are not, the migration program disambiguates them.
Provide the patron files in comma delimited format as a standard Koha extract. The following fields are expected. Indicate the local field names for the expected fields in the Patrons tab of the Koha Field Mapping Form.
| Field Name | Notes |
|---|---|
| borrowernumber | Not repeatable. |
| categorycode | use in User Group tab in Koha Migration Form |
| sex | |
| surname | |
| firstname | |
| initials | |
| dateenrolled | |
| dateexpiry | if empty, migration fills in conversion date + 1 year |
| branchcode | use in Campus Code map in Koha Migration Form |
| debarred | |
| date of birth |
User Identifiers
There can be a number of fields in the patron record that are user identifiers. The types of identifiers that are available for migration into Alma are listed in the left column. The typical expected field names from Koha are in the right column. Change the field names and/or order of the right column to suit your library’s extract. The values in the left column cannot be changed. Use the values in the left column to select the appropriate primary identifier in the Questionnaire tab of the Koha Migration Form.
| Alma Identifier Type | Koha Field Name |
|---|---|
| UNIV_ID | userid |
| BAR | cardnumber |
| ADDL_ID_1 | COLLEGEID |
| ADDL_ID_2 | |
| ADDL_ID_3 | |
| ADDL_ID_4 |
User Preferred Address
There may be a number of addresses, phone numbers, and email addresses in the Koha patron record. You may decide which addresses, phone numbers, or email addresses are the preferred ones in Alma. If the preferred entry is empty, the secondary one is preferred. Additionally, select an address type for each address: Home, School, Alternative, Work, All. Phone options on the field mapping form are similar to the address options. Phone types are: Home, Mobile, Office, OfficeFax, All. Email types are: Personal, School, Work, All.
If the country code or name is included in this address, the migration programs do not standardize it.
| Address | Local Field Name for Preferred address | Local field name for secondary (non-preferred) address |
|---|---|---|
| ADDRESS_LINE_1 | address | B_address |
| ADDRESS_LINE_2 | ||
| ADDRESS_LINE_3 | ||
| ADDRESS_LINE_4 | ||
| ADDRESS_LINE_5 | ||
| ADDRESS_CITY | city | B_city |
| ADDRESS_STATE | state | B_state |
| ADDRESS_CODE | zipcode | B_zipcode |
| ADDRESS_COUNTRY | If country is provided, it must be a three-letter ISO country code, which can be found here https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3 | |
| ADDRESS_NOTE | ||
| ADDRESS_START | ||
| ADDRESS_END | ||
| ADDRESS_TYPE | Select an address type for the preferred address, using the dropdown box on the field mapping form | Select an address type for the secondary (non-preferred) address, using the dropdown box on the field mapping form |
User Statistical Categories
There may be a number of fields in the patron record that function as a statistical category only, for example, a student’s department or major. The way the student borrows can be determined by the P TYPE, but you may want to track the department, so that you can get more detailed statistics on how Law students borrow, for example. Since Koha has a large number of fields that are customizable, we provide you the option to map the data from any field to the User Statistical Categories in Alma.
| User Statistical Category | Local Field Name | Field Label |
|---|---|---|
| USER_STAT_CATEGORY | DEPT: | |
| USER_STAT_CATEGORY | MAJOR: | |
| USER_STAT_CATEGORY |
Up to 10 incoming fields can be mapped. To map the values, use the UserStatCategories map in the Koha Migration Form. If a value is not found in the map, it is migrated as is. If you use a label, the userStatCategory map tries to map the field including the label. The first column in the userStatCategory map would be: LABEL:value, for example: SCHOOL:Law (note that there is no space between the colon and the fields). The migration file validation tool does not provide a colon; if you want this colon for ease of handling, then provide it in the label as above.
The Alma Migration Engine replaces a hyphen (-) with a blank. Do not use a hyphen as a statistical category, as it will not be mapped properly.
Notes
Any additional fields not listed above may be put into notes. The possible note fields in Alma items are listed in the following chart in the Note Name column. The fields listed in the Default Local Field column are those that are expected by Ex Libris. If you use other field names or have fields that you want to include in the migration but are not expected by Ex Libris, you can rearrange, add, or subtract fields on the right, as necessary. If you want to include multiple local fields in the same Alma note, make as many copies of the line in the spreadsheet as needed for all note name/local field combinations.
| Note Name | Information |
|---|---|
| LIBRARY_NOTE | |
| BARCODE_NOTE | |
| ADDRESS_NOTE | |
| OTHER_NOTE | OTHER_NOTE is set as User Viewable by the migration programs |
Loans/Circ Transactions
Extract only current circulation transactions.
Provide the loan files in comma delimited format as a standard Koha extract. The following fields are expected. Use the Loans tab on the Koha Field Mapping Form to indicate local field names for the expected fields.
| Field Name | Notes |
|---|---|
| barcode | alpha/numeric |
| issuedat | date |
| borrowernumber | numeric |
| date_due | date |
Any additional fields not listed above may be put into notes. The possible note fields in Alma items are listed in the following chart in the Note Name column. The fields listed in the Default Local Field column are those that are expected by Ex Libris. If you use other field names or have fields that you want to include in the migration but are not expected by Ex Libris, you can rearrange, add, or subtract fields on the right, as necessary. If you want to include multiple local fields in the same Alma note, make as many copies of the line in the spreadsheet as needed for all note name/local field combinations.
| Note Name | Default Local Field |
|---|---|
| NON_PUBLIC_NOTE | # OVERDUE |
Requests/Holds
Extract only those hold requests where the item is waiting on the hold shelf for pickup. It is possible to limit the hold request extract file to these kind of requests by linking to the item and only retrieving those hold requests where an item hold status value = ‘!’.
Provide the request files in comma delimited format, as a standard Koha extract. The following fields are expected. Indicate the local field names for the expected fields on the Requests tab of the Koha Field Mapping Form.
| Field Name | Notes |
|---|---|
| cardnumber | alphanumeric |
| date reserved | date |
| priority | alphanumeric |
| barcode | alphanumeric |
| homebranch | alphanumeric |
| holdingbranch | alphanumeric |
| hold status | alphanumeric |
Any additional fields not listed above may be put into notes. The possible note fields in Alma items are listed in the following chart in the Note Name column. The fields listed in the Default Local Field column are those that are expected by Ex Libris. If you use other field names or have fields that you want to include in the migration but are not expected by Ex Libris, you can rearrange, add, or subtract fields on the right, as necessary. If you want to include multiple local fields in the same Alma note, make as many copies of the line in the spreadsheet as needed for all note name/local field combinations.
| Note Name | Default Local Field |
|---|---|
| NON_PUBLIC_NOTE |
Separate Fine/Fee File
Most Koha customers do not provide a separate fine/fee file. Usually, the patron field contains a ‘MONEY OWED’ field and the migration programs make a single fine based on that field.
However, if you are able to extract a separate fine/fee file with exact fines for specific patron and item combinations, use this format described here. It is our understanding that certain Sierra versions support this separate fine/fee file. For more information, see the entry in the Ex Libris Developers’ portal on Sierra fine export: https://developers.exlibrisgroup.com...ra-III-to-Alma.
If you provide a separate fine/fee file, then be sure to NOT map the ‘MONEY OWED’ field in the patron record, so that duplicate fines are not created.
Extract only current fines and fees. Only outstanding amounts are migrated – for example if the original fine was $20, and the patron paid $5, then a fine is generated of amount $15.
Provide the fine/fee files in comma delimited format as a standard Koha extract. The following fields are expected. Use the Fines & Fees tab on the Koha Field Mapping Form to indicate local field names for the expected fields.
| Field Name | Notes |
|---|---|
| borrowernumber | alphanumeric |
| barcode | alphanumeric |
| homebranch | alphanumeric |
| amountoutstanding | alphanumeric |
| returndate | alphanumeric |
Any additional fields not listed above may be put into notes. The possible note fields in Alma items are listed in the following chart in the Note Name column. The fields listed in the Default Local Field column are those that are expected by Ex Libris. If you use other field names or have fields that you want to include in the migration but are not expected by Ex Libris, you can rearrange, add, or subtract fields on the right, as necessary. If you want to include multiple local fields in the same Alma note, make as many copies of the line in the spreadsheet as needed for all note name/local field combinations.
| Note Name | Default Local Field |
|---|---|
| FF_COMMENT |
Acquisitions
No acquisitions files are expected from Koha systems. However, if your library is able to export acquisitions data such as vendors, orders, and funds, contact your Ex Libris project manager.
Appendix – File Delivery and Form
Each time data files are provided to Ex Libris in the formats indicated in Expected File Formats, place them on the secure drop-point on the Ex Libris MFT server with the access credentials provided by your Ex Libris project manager.
The following is the default naming convention:
CustomerName+DataType+sequence+date+[.].
For example: centralu_bib_01_20120420.mrc, centralu_bib_02_20120420.mrc, centralu_bib_03_20120420.mrc, etc.
Ex Libris recommends a maximum of 200,000 records per MARC file and 400,000 for other types of records (items, orders, etc).
All records in a single file must be homogenous – all of the lines in the file must have the same number of fields, and those fields must contain the same type of data. Additionally, all of the records must be delimited in the same manner.
Provide the Koha Delivered Files List along with the submitted files.