- A step-by-step guide to filling out the Koha Migration Form.
- An explanation of the data files expected from Koha, along with the fields for each file, and migration rules for Koha to Alma.
- 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 subset 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).
Recommendations for Using this Guide
- Physical to Electronic
- Requested files from Koha - a description of the data files and fields expected from Koha
- Questionnaire Tab – Instructions for individual questions asked on the Questionnaire tab of the migration form.
- Individual Tabs – Instructions for how to fill out individual tabs on the migration form. (Examples: Alma Library Tab, User Group Tab, PO Line Type Tab).
- Further Explanation – Explanations of migration processes that need more explanation and/or do not need customer input.
- This document is intended to complement the Koha Migration Form - an Excel spreadsheet that is read by the migration programs. It provides further information regarding the migration process and the steps required for migration to Alma.
- Prerequisites: Basic knowledge of Alma and Koha key concepts and architecture and the requirements (including the migration-related approach) described in Getting Ready for Alma and Discovery Implementation, as well as Electronic Resource Handling in Alma Migration.
- It is recommended that you view the Introduction to the Alma Configuration Process video session before completing the migration form, as the mapping and migration of libraries and locations have implications for subsequent configurations.
Requested Files from Koha
Koha Field Mapping Form
Koha Delivered Files Form
- 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.
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|
|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
|Expected Field Name||Value||Notes|
|SUMM_TAG||Five characters; tag+2 indicators. May use # as wildcard, for example, 866## or 86#3#. Wildcard allowed for third digit and indicators but not first two digits. To indicate a space character, use b, for example 866b1.|
|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.|
|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|
|Damaged status||$4||Use in item base status|
|Collection code||$8||Use in location map|
|Holding library||$b||Use in location map|
Create Date is not retained in Alma; if you wish to keep this, move it to a note.
If $i (inventory number) is provided, then this value is used as the inventory date.
|Inventory number||$i||inventory number|
To see this value in Alma, search for the item under 'Physical Items' and on the results list click 'Other details'.
Alma increments the loan count for items currently on loan, so it is recommended that you send (loans - 1) for currently loaned items.
|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'.|
|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|
|Receive Number||In order to use, you must configure an item sequence of type Receiving Number|
|Weeding Number||In order to use, you must configure an item sequence of type Weeding Number|
|Weeding Date||use with Weeding Number|
|Note Name||Local Subfield||Note Label|
|PUBLIC NOTE||Public Note|
Item Statistics Notes (STAT_NOTE_*) can use controlled vocabulary when statistics_note_controlled is set to true. For more information, see Configuring Item Statistics Notes.
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 February), 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.
With the exception of the item_key and barcode, all other fields will force blank if an empty field is provided. In other words, if you have an item description in Alma, and you provide a blank description in this file, the incoming blank will be 'written' to Alma, meaning the Alma description will be deleted.
We recommend that EnumX and ChronX fields contain only numbers, for example '12' instead of 'Vol. 12' and '2' instead of 'Feb'. However, it is programmatically time-consuming to distinguish between an invalid use (Vol. 12) and a valid use (12A), so in the interest of processing quickly, we allow any string in EnumX and ChronX fields. Do not provide a full date in a single field. Split any dates into three, for example 4 Feburary 2020 is ChronI=2020, ChronJ=2, ChronK=4.
Even though it is not recommended, if for any reason you need to provide a full date in a single field, put a tick (') before the date in the Excel cell so that it is treated like text (instead of the Excel date format).
Provide the secondary item file in Excel format (xls or xlsx) format, with the following fields:
|Expected Field Name||Notes|
Provide either item_key or barcode, but not both. If both are provided, item_key is preferred
Always provide both fields, even when one is empty. E.g.
|description||Provide in a format such as: Vol. 12, No. 6 (February 2015)|
|enumA||For example, “12”.|
|enumB||For example, "6".|
|chronI||For example, "2015"|
|chronJ||For example, "2".|
Customer Input - Inventory
Institution Code, Customer Code, Institution Name, Customer Name, Time Zone
List Prefix for bibs from SFX or other management system
MARC Organizational Code
Do you use internal system numbers in Linked Entry fields?
Indicate if you use internal system numbers in linking fields. Internal system numbers from your legacy system are not continued in Alma, and therefore should be changed to MMSID (the Alma internal system number).
MARC fields: $w subfield for tags 76x-78x, 80x, 81x, and/or 83x
Unimarc fields: $1 subfield with prefix 001 for fields 423, 461, 462, 463, 464 [example: bib key 99999 in tag 461 = 461 $100199999]
Options: If you answered Yes to this question, the internal system numbers in the subfield $w or $1001 of the specified tags are converted from the former system number to the Alma system number.
Internal record designation for Linked Entry fields $w
Options: If you answered Yes to the previous question and the internal system numbers have a prefix, enter the value to be matched to identify the local system number. If the system numbers in $w or $1001 do not have a prefix, or if you answered No to the previous question, leave this question blank.
Further information on LINKED_ENTRY_W and LINKED_ENTRY_PREFIX: When bibliographic records are related to each other, such as a journal title that is superseded by a second journal title, your previous ILS may store the information in bibliographic fields 76x-78x, 80x, 81x, and 83x $w for MARC, and 423, 461, 462, 463, 464 for Unicode. If the number in the $w or $1001 of the linking tags is the internal legacy ILS system number, these numbers must be changed to the Alma representation of the system number. If your library does not use the internal system number to link and instead relies on more general identifiers such as the ISBN, ISSN, or shared cataloging DB (OCLC or DLC), these numbers are not modified.
In Alma, the system numbers in the linking field are used to link two related bibliographic records together using the related records process. Related records can be found by clicking the More Info link on the Alma Search Results page. For more information on configuring related records, see Configuring Related Records for Physical Inventory.
Indicate which 852 subfields to use to determine unique holding records
Do you want to use a call number in the generated holdings records?
Options: Yes or No
Further Information: You may choose to generate holding records without any call number, so that the 852 contains only $b (library) and $c (location). Values in the incoming Item Call Number field are placed in the Alma Item Call Number, and AltCallNo is not used when this is set to Yes. Further, customers should only use ‘bc’ for the 852_CALL_NO_FOR_HOL question when this is No.
Move 852$c to Another Subfield
Limit exported records by location
Bib Key Prefix
Move 001/003 to 035 or 935
Options: If your incoming bibliographic records have a number in the 001, then the migration programs move it elsewhere as (<003>)<001>. For example: (OCoLC)12345. To move to the 035, which is the default, then select 035 in the dropdown. If you are part of a consortium and are using OCLC numbers to determine matching records when linking to the NZ, you may wish to move this number to the 935 so that the moved number does not interfere with another matching key you may be using. If you are not linking to the NZ, then this question is likely not useful. Default: 035
Ex Libris marks the moved 035 or 935 with $9 ExL to indicate that the migration programs generated this field.
Further information: If an 035 exists in the record already with the identifier that was in the 001, then a second (duplicate) tag is NOT made. Also, when checking if the identifier already exists, the migration programs compare to the $a only. Meaning, if an existing tag contains
035 $a(OCoLC)12345 $z (OCoLC)54321
then the existing 035 $a is considered a duplicate and a second tag is not created.
Add institution suffix to Bib ID
Options: When moving the legacy bibliographic identifier to the 035 or 935, you can choose to add the institution code to the end of the string, like 12345-34ABC where 12345 is the legacy bib ID and 34ABC is the institution code. This may be used in conjunction with other bib identifier options, such as BIB_KEY_PREFIX and MARC_OC.
Yes = include suffix
No = do not include suffix
Use subfield indicators in item call number (AltCallNo)
Options: When generating an Item Call Number field (also known as AltCallNo), you can decide if the string contains subfield indicators. Default = Yes
Yes = $h PZ3.A93 Pr16 $i A975
No = PZ3.A93 Pr16 A975
For more information on when an Item Call Number is generated, see the section Changing the Holding Record Grouping, which depends on the question 852_SUBFIELDS_FOR_HOL.
Add $9 LOCAL to specified tags
Options: Add $9 LOCAL to specified bib tags, for use in consortia where an IZ environment links to an NZ. Tags marked as Local will be kept in the IZ, and not moved to the NZ.
Format for this input: tag + indicator. Use # for any/wildcard, and b for the space character. Separate with semicolon. For a list of acceptable tags, see the Migration Guide for Consortia.
Example: 59###; 69###;960##;970##;090b#
Alma Library Tab
Alma Location Tab
|Koha Location code||Koha Locn Desc||Alma Library||Alma Location Code||Alma Location Desc||Alma External Loc Desc|
|ALMAME_ VALUE_NOT _FOUND||MAIN||UNASSIGNED||Problem location from Migration||Problem: See Library Staff|
Alma Location Name and Alma External Location Name
|Library||Alma Location Code||Alma Location Name||Alma External Location Name|
|Library A||stacks||Main Stacks||Main Stacks|
|Library B||stacks||Main Stacks||Main Stacks|
|Library A||archa||Archives A||Archives|
|Library B||archa||Archives B||Archives|
|Library A||archstk||Archives Stacks||Archives|
|Library A||archref||Archives Reference||Archives|
|Library||Alma Location Code||Alma Location Name||Alma External Location Name|
- The Alma library is placed in the 852‡b field.
- The Alma location is placed in the 852‡c field.
|Koha Location Code||Alma Library||Alma Location Code||Alma Location Name||Alma External Loc Name||Suppress from Externalization||Electronic Location|
Item Type Tab
Item Base Status Tab
Material Type Tab
Use this tab to migrate any incoming Material type to the Alma Material type. The material type is not mandatory; if no material type is indicated for an item, one will be generated based on information from the bib fixed fields.
Incoming Material Type: The value in the material type field of the incoming item.
Material type Description: The description of the material type, for information only. This column is not used during the mapping process.
Alma Material Type: The Alma value for the material type. Material types in Alma are fixed. You cannot add any new types to the list. Select the appropriate material type from the drop-down list.
If this field is not provided in the extract, Alma migration assigns the item material type based on the fixed fields in the bib as described in section Material Type from Bib Fixed Fields below.
Shelving Scheme Tab
Further Explanation – Inventory
- Suppressed bibliographic records as described above in the Suppressed Bib Tab of the migration form.
- Australian customers will have ALL Bibliographic records marked for Libraries of Australia Publish, if relevant.
- OCLC records (records with an 035 |a with an OCLC-official prefix) will be marked for OCLC publish, if relevant.
- The LDR position 9 (character coding scheme) is set to a indicating Unicode.
- The Alma library is placed in the 852‡b field.
- The Alma location is placed in the 852‡c field.
Determining Groups for Holding Record Creation/Matching
- Item 1, 2 in Location A
- Item 3, 4 in Location B
- Item 5 in Location C
Changing the Holding Record Grouping/Matching
Call Number Type
- If the barcode is empty, leave as empty in Alma.
- If the barcode exists, but is not unique:
- First item barcode encountered – migrate as is.
- Second and subsequent item barcodes encountered – migrate as <item barcode>-<item id>
Because it is possible to use the barcode as the link between item and loan, request, or fine, if one of those is linked to an item with a duplicated barcode, it will be linked to the item with the unsuffixed barcode.
Areas/Fields Not In Scope
|categorycode||use in User Group tab in Koha Migration Form|
|dateenrolled||Create Date is not retained in Alma; if you wish to keep this, move it to a note.|
|dateexpiry||may be left empty|
|branchcode||use in Campus Code map in Koha Migration Form|
|debarred||If there is a date here, then make a block on this patron, and put the date in the block note.|
|date of birth|
|Alma Identifier Type||Koha Field Name|
User Preferred Address
|Address||Local Field Name for Preferred address||Local field name for secondary (non-preferred) address|
|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_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
|User Statistical Category||Local Field Name||Field Label|
If you use this prefix, be sure to use the prefix again in the Migration Form Mapping tab for User Stat Categories, in column A (incoming data). In the Field Mapping form, provide labels to the right of the field:
Then, in the migration form, use that label as a prefix to the values in the field. Be sure to put a space between the label and the code:
In the case above, you can see that if there were no prefix to the fields, it would not be possible to distinguish between 'b' from PC1 and 'b' in PC2.
|OTHER_NOTE||OTHER_NOTE is set as User Viewable by the migration programs. This is the only note which migration marks as user viewable.|
|Note Name||Default Local Field|
|date reserved||This value is placed in REQUEST_DATE, the date the request was made|
not provided by
Koha but requred
|HOLD_DATE - date the item was placed on the hold shelf. Default: migration date|
|EXPIRATION_DATE - date request expires. Default: migration date + 30 days|
|Note Name||Default Local Field|
Separate Fine/Fee File
|Note Name||Default Local Field|
Customer Input - Fulfillment
Enter a two-letter code for the default conversational language for your users
Which identifier should be used as the patron's Primary Identifier?
How should we handle duplicate identifiers in the same patron?
Options: Alma does not allow duplicate identifiers anywhere, even in the same patron. If the patron has the same number in two or more different identifier types, we can either not migrate the second one, or disambiguate it with -1, -2 etc.
DISCARD: do not migrate the second and subsequent identifiers
ADD_SUFFIX: add -1, -2, etc
Currency for patron fines
Merge Patron Prefix
Options: If you are combining data from two or more separate databases into a single combined institution in Alma, then indicate a prefix here that will be used to distinguish the incoming patron record original IDs. This prefix is only added to the internal patron identifier, it is not added to barcodes or usernames or UNIV_ID. If you are not merging institutions, leave this question blank.
See also: BIB_KEY_PREFIX
User Group Tab
- Which identifier should be used as the patron's Primary Identifier?
User Stat Categories Tab
Before filling in this tab, specify in the Patrons tab of the Generic to Alma Field Mapping form which fields from your legacy ILS are migrated to statistical categories in Alma. You can include a label before each category to distinguish between categories in different fields. For example, you can have LAW in USER_CATEGORY1 and also LAW in USER_CATEGORY2. If desired, use a prefix to distinguish between the two, for example, CAT1: LAW and CAT2: LAW.
The migration engine adds a space between the label you specified in the Field Mapping form and the value. So if you included a label 'CAT:' in the field mapping, then use 'CAT: a' here (if 'a' is an incoming value).
Campus Code Tab
Fine Fee Type Tab
Further Explanation – Fulfillment/Patrons
- Provide a field called INTERNAL_EXTERNAL in the Koha patron extract, containing either “INTERNAL” or “EXTERNAL”.
- Identify patrons as internal or external by user group on the Koha Migration Form, User Group tab, Internal? Yes or No column. For example: all faculty are EXTERNAL and all community borrowers are INTERNAL.
Even though there is no Acquisitions data expected, we must still set up the Acquisitions environment in order for you to start using it. Answer the following questions about Acquisitions in the Migration Form.
What is your currency?
Fiscal Period Cycle Pattern
Which year do you use to name the fiscal year?
- second – if fiscal period runs July 1 2014 through June 30 2015, then the fiscal year is named 2015.
- first – if fiscal period runs July 1 2014 through June 30 2015, then the fiscal year is named 2014.
Current Fiscal Year
- Determine by date of conversion – The conversion program uses the fiscal period that includes the date of conversion.
- (year) – select the name of the current fiscal year, based on the previous two questions.
Physical to Electronic (P2E) Processing
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'.
If you provide a bibliographic record in the P2E file, the migration programs will generate an electronic resource for the bib, even if there is no valid URL. An example of an invalid URL might be an 856 tag with an indicator which does not match the specific indicator in the question P2E_LINK, below. For example, if you say that we use 85641u for the P2E_LINK, and you provide a bib record *without* a 85641u but that bib record is in the p2e file, then we will generate a local e-resource without any link at all (an empty resource). Be careful which bibs are placed in the bib file.
Further, the P2E process attempts to identify an order related to the identified inventory for conversion to electronic. Similarly to items and holdings, orders are initially migrated as print and are transformed to electronic through the p2e process. See the guide https://knowledge.exlibrisgroup.com/Alma/Implementation_and_Migration/Migration_Guides/Electronic_System_Migrations/Electronic_Resource_Handling_in_Alma_Migration for more information.
- Specific indicators: 85641u – only tags with 41 as the indicator is used.
- No indicator (# is used for a blank character, for example: 8564#u) – only tags with 4<blank> as an indicator are used.
- All possible indicators: 8564*u – tags with 4 as the first indicator are used. The second indicator is not taken into account.
The space character operates the same way as an asterisk (*), for example: 8564 u is the same as 8564*u.
Special Request: If you need to specify multiple specific indicators, for example 85641 and 85642, it cannot be coded in the migration form but your ExL representative can make a special request to the migration team.