Koha to Alma Data Delivery and Migration Guide

Migration Overview

Koha is an open-source Integrated Library System. Support is provided by various companies but it is possible for libraries to operate Koha with no external support.

This document serves two purposes:

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.

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 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).

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. Customers 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.

Recommendations for Using this Guide

This document is divided into four areas:

Inventory
Fulfillment
Acquisitions
Physical to Electronic

Each area has the following sections:

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.

We recommend that you look at the Questionnaire tab section and the individual tabs in each area to assist in filling out the migration form.

If you have further questions about any of the data input or about the migration in general, see the more detailed explanations in the Further Explanations sections.

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.

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

Alma requires bibliographic, holdings, and item records. Koha has only bibliographic records and items. On migration, a holding record is created based on information in the Koha item record. See the MARC Holding Records section for more information.

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.

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## 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.

Call Number from Bib tag (special processing)

A few customers may need to use special processing which inserts a call number from the bib into related item records (CSV).

This special processing takes a call number from a tag in the bib record, saves it on the side, and then inserts the call number into the separate item records which are delivered in the embedded item record.

Configuration for this special processing is found at the bottom of the 'Bibs & P2E' tab on the Generic Field Mapping form. All subfields must come from the same tag.

Expected Field Name	Repeat-able?
CALLNO_TAG	The tag which contains call number information. In format: TTTii (tag + indicators) may include wildcard # for the indicators, but not the tag. E.g. 084## and 0841# are acceptable, but 08#1# is not acceptable
CALLNO_SUBF_H	Indicate the subfield from the bib tag which will go into 852 $h. Usually this is 'a'
CALLNO_SUBF_I	Indicate the subfield from the bib tag which will go into 852 $i.
CALLNO_SUBF_J	Indicate the subfield from the bib tag which will go into 852 $j.
CALLNO_SUBF_K	Indicate the subfield from the bib tag which will go into 852 $k.
CALLNO_SUBF_M	Indicate the subfield from the bib tag which will go into 852 $m.

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	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.
purchased price	$g
Serial enumeration	$h
Inventory number	$i	inventory number
Storage Location ID		This is not specifically an expected subfield, but customers may put any incoming subfield here.
total checkouts	$l	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.
Call number	$c	This call number field is used when generating a holding record, and to match items to holdings using the 852_subfields_for_hol routine. This value may be placed in the Item Call Number field if 852_subfields_for_holdings is bc and the item call numbers do not match. Item Call Number (below) takes precedence, however, so if Item Call Number is filled, then the non-matching call number is lost. You may also import a call number for this field from a different bib tag using the CALLNO* fields on Bibs & P2E tab.
Item Call Number	$o	If this is present, then the value will always be placed in ITEM_CALL_NUMBER. This value takes precedence over a possible value from the above 'Call Number', according to the descriptions in "Determining Groups of Holding Records" and "Changing the Holding Record Grouping" sections below.
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
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

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	Local Subfield	Note Label
PUBLIC NOTE		Public Note
FULFILMENT_NOTE
FULFILMENT_NOTE
NON_PUBLIC_NOTE_1		Nonpublic Note
NON_PUBLIC_NOTE_2		shelving location
NON_PUBLIC_NOTE_3		owning library
STAT_NOTE_1
STAT_NOTE_2
STAT_NOTE_3

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
item_key	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.
barcode
description	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

Customer Input - Inventory

Questionnaire Tab

Institution Code, Customer Code, Institution Name, Customer Name, Time Zone

Codes: INST_CODE, CUST_CODE – these are filled in by Ex Libris

INST_NAME, CUST_NAME – these are mandatory and must be filled in.

Default: N/A

Options: This question is mandatory.

INST_NAME and CUST_NAME: Fill these fields in with your institution’s name and your customer name (this is only different from the institution name if you are part of a consortium).

List Prefix for bibs from SFX or other management system

Code: SFX_PREFIX

Default: ‘(SFX)’

Options: string. If not indicating a link resolver management system, leave blank. Multiple strings are allowed, use a semicolon to separate: (SFX);WaSeSS;EBC

Further Information: If your Koha catalog contains records imported from SFX or another electronic resources management system and you are also migrating bibliographic records directly from SFX or the other management system, this may result in duplicate bibliographic records in Alma. You can enter a prefix here so that the migration programs can identify these bibliographic records and not migrate them to Alma to avoid creating duplicate SFX records in Alma. The migration programs do not make any attempt to physically merge the two records into one.

The default response to this question is (SFX), but you can enter any prefix that represents the bibliographic records that you want to exclude from loading into Alma. The migration programs search for the string in the 035 $a field of the MARC record. If you do not want to exclude any such records, leave this field blank.

If the migration programs identify bibliographic records containing the prefix in the 035 $a and the records in Koha are connected to a purchase order line and/or physical items, these bibliographic records are still migrated so that the purchase order and/or items can be migrated, but they are automatically suppressed in Alma to avoid end-user discovery duplication.

MARC Organizational Code

Code: MARC_OC

Default: None; this is not mandatory

Options: Enter your MARC organizational code, which will be used to construct the former system number in Alma. Only one code is allowed.

Further Information: The migration moves the value in the exported record’s 001 field (Koha bibliographic system number) to the 035 $a field:

(MOC)<Koha record id>-<customer code>

<(moc)> is the MARC Organization code specified here. is the <customer code> specified in the CUSTOMER_CODE question above.

For example: (AbC)123456-01abc

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]

Code: LINKED_ENTRY_W

Default: No

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

Code: LINKED_ENTRY_PREFIX

Default: Blank

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

Code: 852_SUBFIELDS_FOR_HOL

Default: bc (library and location only, not call number)

Options: To group all items on a single bibliographic record by library/location only, indicate bc here. If you have many items on the same bibliographic record in the same library/location but different call numbers WITHIN that library/location, and you want each of them to have their own distinct holding record, specify additional call number subfields. Acceptable subfields: bchijklmp.

The library and location codes are matched after the Alma Location Mapping has been performed, meaning the match is done on the Alma version of the library/location codes.

See sections: Determining Groups for Holding Record Creation/Matching, Changing the Holding Record Grouping/Matching

Do you want to use a call number in the generated holdings records?

Code: CALL_NO_IN_HOL

Default: Yes

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

Code: MOVE_852C_SUBF

Default: k

Options: optional

Further Information: If you have data in your Koha holdings record 852 $c, it must be moved to a different subfield to accommodate the two levels of location in Alma – Alma library and location, which are in 852 $b and $c. Decide to which subfield you want the $c information moved. If nothing is specified or the response is incorrect (such as Yes or No instead of specific subfield), the default subfield is $k. Subfield $c is only moved for the relevant 852 tag. This means that if there are multiple 852 tags in the same holding record, the $c is only moved for the first 852 tag to make room for the sublocation in $c in Alma.

Limit exported records by location

Code: LIMIT_BY_LOCATIONS

Default: No

Options: If your export contains all of the data from a shared database, and you want to only migrate a part of that export to Alma, the migration programs can filter the data according to locations listed on the Location tab. In this case, the ALMAME_VALUE_NOT_FOUND line on the Location tab is not used. Inventory and Acquisitions are filtered by locations on the Location tab, and Fulfillment is filtered based on campus codes in the Campus Code tab. Use this option only if agreed upon with your Ex Libris project manager.

Bib Key Prefix

Code: BIB_KEY_PREFIX

Default: empty

Options: If you are combining data from two or more separate databases into a single combined institution in Alma, indicate a prefix here that will be used to distinguish the former system numbers in Alma after migration. For example, the different systems likely had completely different bibliographic records for system number 12345 and you want to be able to search for the specific bibliographic record from your own institution after go-live. The prefix does not include a hyphen so if you want a hyphen in the number (for example, PQ-12345), include it in the string. If you are not merging institutions, leave this question blank.

See also the MERGE_PATRON_PREFIX in Fulfillment.

Move 001/003 to 035 or 935

Code: 001_035_935

Default: 035

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

001 12345

003 OCoLC

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

Code: BIBID_INST_SUFFIX

Default: No

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)

Code: ITEM_CALLNO_SUBFIELD

Default: Yes

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

Code: NZ_LOCAL_TAGS

Default: empty

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#

The wildcard works only for the third digit of the tag and the indicators. Examples:

CORRECT: 95###

INCORRECT: 9####

Also, 900-949 cannot be used here, as described in the Migration Considerations for Consortia guide.

Alma Library Tab

Use this tab to create a list of Libraries in Alma. At least one library is mandatory.

Alma Library Code: Maximum 10 characters. Mixed case is valid, but not recommended. Do not use special characters or spaces. Allowed: - and _ (hyphen and underscore). Not allowed: !@#$%^&*()+=/?><.,\|]}[{`~ or the space character.

The Alma Library Code may not be the same as the Alma Customer Code nor the Alma Institution Code .

Alma Library name: Maximum 255 characters. Visible to the public. This must be unique. For example, you cannot have two libraries with code LIBA and LIBB and have them both called 'Library'. They must have different names.

Address lines: Alma allows you to specify address, phone, and e-mail information about each library. It is mandatory for a library to have a shipping/billing address in order to place orders in Alma. The migration process sets the designated address provided with all possible types in Alma (shipping, billing, claiming, etc.). At least one address line is mandatory.

Email: An email address is mandatory. The migration process sets the email address provided with all possible email address types in Alma.

Phone: The phone number must contain dashes (nnn-nnn-nnnn). A phone number with no dashes is not accepted by the migration program. Not mandatory.

Default language: Indicate the language of patrons and/or staff members if it differs for each library. Use two-letter codes as defined in ISO 639-1. Consult the codes at https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes.

Further Explanation: Both Koha and Alma have two levels of location. Koha uses holding library and collection code and Alma uses library and physical/shelving location. Locations in Koha are generally analogous to the physical/shelving locations in Alma. Libraries are higher level units that contain groups of locations. Alma libraries serve as higher-level repositories for physical records and also determine policy groupings for their management and fulfillment. The lower-level physical location does not determine policy for an item and is only the physical shelving location or collection. All physical resources in your institution must belong to a library.

During the migration process, group your Koha locations into library groupings. The first step is to determine the list of libraries, using this tab. Next, map locations into Alma libraries and locations using the Alma Location tab.

If you use an error library (for example “EMPTY”) in the ALMAME_VALUE_NOT_FOUND line of the Location Mapping tab, be sure to list that library here on the Library tab.

Alma Location Tab

Use this tab to map your Koha locations to Alma libraries and locations. Mandatory.

Include ALL locations of ALL types, including electronic types that may ultimately be deleted in Alma. They still need to be provided in the Location tab mapping.

Koha holding library code: Value from the Location field in the item extract, 952 $b, in the embedded item tag in the bibliographic record. The ALMAME_VAL_NOT_FOUND line is required to catch any location codes you may have missed.

Koha collection code: Value from the collection field in the item extract, 952 $8, in the embedded item tag in the bibliographic record. The ALMAME_VAL_NOT_FOUND line is required to catch any location codes that you may have missed.

Alma Library Code: The library that will contain this location in Alma. This code must be present on the Alma Library tab, column A. The match is case-sensitive.

Alma Location Code: The new location code for this location in Alma. It can be a maximum of 10 characters. You can use the same location codes in Alma that you used in Koha, but this is not required. You may also use this form to collapse locations if desired, for example, refa and refb in Koha both map to ref in Alma. Mixed case is valid, but not recommended. Do not use special characters or spaces. Allowed: - and _ (hyphen and underscore). Not allowed: !@#$%^&*()+=/?><.,\|]}[{`~ or the space character.

Call Number Type: List the call number type for any newly created holdings records, based on the values for the 852 first indicator. (http://www.loc.gov/marc/holdings/hd852.html). If we cannot determine the call number type from the item record itself, we use this as a default for all items in the location.

Alma Location Name: A description for this location as seen/used by library staff members. The same location name cannot be used for different locations in the same library, but the same location name can be used for different locations in different libraries. See the examples in the Further Information section below for what is acceptable and not acceptable. Maximum 255 characters.

Alma External Location Name: A description for this location as seen/used by the public. The same name can be used for as many different locations as desired. For example, the location names may be Archives A and Archives B, but the external location names can both be Archives. Maximum 255 characters.

Electronic Location? (Yes or No): Used by the P2E migration process to determine if a holding/item/order should be converted to electronic. See the Physical to Electronic (P2E) Processing section for more information.

Suppress from Externalization? (Yes or No): Indicate if the location should be suppressed from being visible to the public. The items are not marked as suppressed, but no holdings or items with this location code are exported to Primo.

Further Information: Do not leave the Alma Location and Library Code fields blank. If you want to stop using a location code after migration, map the Koha code to an easily identifiable code such as XXX or unused just in case any stray items are still in your Koha database.

ALMAME_VALUE_NOT_FOUND

The ALMAME_VALUE_NOT_FOUND line must be included at the top of the list of locations, in case any location codes were overlooked when completing this map. For example, you may think that you do not have any items left in a certain collection, so you leave it off the location map. However, there may be one or two items left, or a stray holding record, etc.

By default, the location code for the ALMAME_VALUE_NOT_FOUND line is UNASSIGNED, which is the default catch-all in Alma in production mode. We recommend that you select your primary/largest library as the library code for the line, for example MAIN as in the example line below. In this case, the items inherit the configurations for the MAIN library. You may also decide to use a completely new library, such as EMPTY. However, if you use a library that is new, like EMPTY, then be sure to also include it on the Library 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

Post-migration, search for items in the UNASSIGNED location and correct the records appropriately.

Alma Location Name and Alma External Location Name

The Alma Location Name column contains the names of the location codes that are displayed in the staff interface. The names cannot be repeated in the Location Name column when the location codes both belong to the same library, but you can use the same name for two different locations, if these locations belong to different libraries. The Alma External Location Name column contains the names of the location codes that are displayed to library patrons. These names can be repeated within the column without regard for libraries. For example:

The following is acceptable:


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

The following is not acceptable:


Library	Alma Location Code	Alma Location Name	Alma External Location Name
Library A	archstk	Archives	Archives
Library A	archref	Archives	Archives

The Alma library and Alma location are put in the following places in the migrated or newly created MARC holdings record:

The Alma library is placed in the 852‡b field.
The Alma location is placed in the 852‡c field.

Collapsing Locations

This mapping table can be used to collapse location codes – that is, two or more location codes in Koha can map to a single location code in Alma. The Alma location and library code fields may not be empty. If you want to stop using a location code on migration, map the Koha code to an easily identifiable code such as XXX if any stray items are still in your Koha database.

If you collapse location codes, you may have lines in the table such as the following:


Koha Location Code	Alma Library	Alma Location Code	Alma Location Name	Alma External Loc Name	Suppress from Externalization	Electronic Location
reserves	MAIN	RESERVES	Reserves	Reserve	Yes	No
reservesElec	MAIN	RESERVES	Reserves	*ReserveElec*	Yes	*Yes*
reservesShort	MAIN	RESERVES	Reserves	Reserve	Yes	No
reservesPerm	MAIN	RESERVES	Reserves	Reserve	Yes	No

The two values in bold italic above (ReserveElec as the External Location name, and Yes for Electronic location) are not used in Alma. Since the locations are being collapsed, the first line for the RESERVES Alma location is used, and all subsequent lines below it use the values from the first line.

Item Type Tab

Use this tab to migrate the Koha Item Type ($y) to the Alma Item Type. This tab is optional. The item type in Alma is not required, so if you leave this tab blank, no item policies in Alma are created.

Koha Item Type ($y): The value in the item type field of the Koha item. The item type is used to differentiate between items when determining how something circulates.

Koha Description: The description of the Koha item type, for information only. This column is not used during the mapping process.

Alma itemPolicy: The Alma value for the item type. This sheet can be used to collapse item types if desired. Do not use special characters, for example, slashes (/) or spaces in the code.

Alma Description: This description is loaded into Alma as the display text for the item types. These values can be changed after migration. Maximum 255 characters.

You can optionally include an ALMAME_VAL_NOT_FOUND line at the top of the map. If this line is included, any value not found or any blank value is assigned the value in the ALMAME_VAL_NOT_FOUND line. If the ALMAME_VAL_NOT_FOUND line is not included, any value not found, including blanks, is left as blank in Alma.

Item Base Status Tab

Use this tab to map your item statuses to Alma. This tab is not mandatory if you do not want to migrate your item statuses to Alma. There are three different fields that indicate a status in Koha: $4 damaged, $0 withdrawn, and $1 lost. We will use all three fields to determine a base status in Alma.

STATUS (combination of fields $4-$0-$1): The value in the status fields from the Koha item extract. The status typically indicates what is happening to the item, such as in binding, in repair, lost, etc. In Koha we will use three fields as indicated. Separate the values by hyphens, and use * to indicate that any status will match. For example, *-*-1 means: $4 any value, $0 any value, and $1 = 1. This will map to the status “Lost”.

Description: The description of the STATUS code(s). The text in this column is written to the internal note 1 in the item in Alma. Maximum 255 characters.

baseStatus: In Alma, the base status indicates whether or not the item is on the shelf. Indicate whether or not an item with this status is on the shelf. For example, lib use only is on the shelf (1), but withdrawn is not (0).

Further information: Alma has a process type that indicates the status of an item depending on the Alma workflow (item is on loan, item is sent to the bindery, etc.), but the process type is dependent on the corresponding Alma workflow. For migration, all item statuses that are indicated as not on the shelf (0) from Koha are given the process type of TECHNICAL. Further, the item status description field is written to internal note 1 for all items where there was a status, regardless of the shelf/not on shelf designation.

Include any status that may indicate no status, for example Available, but leave column B blank. This migrates the item to Alma with no status at all, which is how Alma indicates that an item has no status. If any status is in your data but is NOT included in column A, it is given a note of Unknown status.

Post migration, you can search for and re-route items with values in the internal note 1 to the appropriate handling or department in Alma. This process can also be used as a configurable criterion for suppressing items from display in the Get It services screens from discovery systems. See Appendix B - Post-Migration Process Statuses for more information.

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

Alma generates a first indicator for the 852 based on the Shelving Scheme tab.

Koha $2 classification: The values in the Shelving Scheme tab as delivered in the extract from Koha. The commonly used values are included in the tab, but you can make additions or changes as necessary.

852 1st Indicator: List the value that should be used in the 852 first indicator field when generating a holding record from the item. For a list of possible values and their description, see http://www.loc.gov/marc/holdings/hd852.html. Note that 7 is not supported on migration. Mandatory.

Description: A description or note for this shelving scheme value, if you need to make a note while deciding the first indicator value. This column is not used in migration.

Do not use an ALMAME_VAL_NOT_FOUND line here, because if an item has a shelving scheme that is not listed or does not have a shelving scheme value, the shelving scheme is taken from the Call Number Type column on the Location tab of the Koha Migration Form.

Further Explanation – Inventory

Bibliographic Records

Bibliographic records are migrated as is and each bibliographic record may modified in the following way during migration:

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.

Alma requires a MARC holding record for all items. During the migration process, the Alma library and Alma location are put in the following places in the MARC holding record:

The Alma library is placed in the 852‡b field.
The Alma location is placed in the 852‡c field.

If the MARC holding record is migrated from Koha, the 852 $b field is replaced with the newly-mapped $b and $c subfields. Use the questionnaire question MOVE_852C_SUBF to preserve any information that was in 852 $c in the Koha holding record. If the MARC holding record is created based on information from the item, then additionally the $h and $i subfields are filled with the call number from the Koha item field (item tag subfields $a and $b).

For Koha customers who are exporting MARC holding records, the migration process attaches migrated items to the MARC holding record. For Koha customers who are not exporting MARC holding records or are exporting partial MARC holdings records, the migration process creates MARC holding records based on information in the Koha item records.

Determining Groups for Holding Record Creation/Matching

If an existing MARC holding record from Koha is found that matches the location or call number of the item, the item is linked to the MARC holding record. Otherwise, a new holding record is created for each group of item records that share the same location or call number. The permanent location and call number in Alma is stored only in the holding record. All items attached to the holding record inherit the permanent location and call number from the holding record. For example, if a bibliographic record has five items with no associated holding record:

Item 1, 2 in Location A
Item 3, 4 in Location B
Item 5 in Location C

The migration program generates three different MARC holdings records, one for each location A, B, or C. The items for each location are then attached to the newly created holdings record. If there are any call numbers that differ from the holding record’s call number, the differing call number is stored in the item’s Item Call Number field.

Changing the Holding Record Grouping/Matching

As part of the migration process, the customer must decide which criteria to use to group or match items to existing holdings and also to determine if multiple items belong on the same holding record. The 852 subfields as mapped from Koha are: $b Library $c Home Location $h Call Number Level 1 $i Call Number Level 2. By default, the migration programs compare $b and $c, but the customer can decide to change this to also include $h and $i based on items in their collection.

For example, if there are four items and a single holding record on the same bibliographic record with the following call numbers:

item 1 $b main $c stacks $h PN 567 $i .M4

item 2 $b main $c stacks $h PN 567 $i .M4

item 3 $b main $c stacks $h PN 567 $i .M4 2010

item 4 $b bio $c flr1 $h PN 567 $i .M457

holding record A $b main $c stacks $h PN 567 $i .M4

When only $b and $c are used to determine a holding record group, the following is the result in Alma:

Holding record A (migrated) $b main $c stacks $h PN 567 $i .M4

item 1

item 2

item 3 (original call number stored in ItemCallNo field in the item)

Holding record (generated) $b bio $c flr1 $h PN 567 $i .M457

item 4

When the holding record group is based on more subfields, for example $b $c $h $i, the following is the result in Alma:

Holding record (migrated) $b main $c stacks $h PN 567 .M4

item 1

item 2

Holding record (generated) $b main $c stacks $h PN 567 $i .M4 2010

item 3

Holding record (generated) $b bio $c flr1 $h PN 567 $i .M457

item 4

Decide which 852 subfields should be used to determine holding record groups by answering the question in the Questionnaire tab of the Koha Migration Form, Indicate which 852 subfields to use to determine unique holding records.

Call Number Type

The 852 field has a first indicator that indicates what the call number type is. You need to indicate what class scheme to use when holding records are created using information from the item. Fill in the Call Number Type column on the Alma Location tab of the Koha Migration form to indicate the class scheme per location.

The available call number types can be found at http://www.loc.gov/marc/holdings/hd852.html.

Supported on migration:

# - No information provided

0 - Library of Congress classification

1 - Dewey Decimal classification

2 - National Library of Medicine classification

3 - Superintendent of Documents classification

4 - Shelving control number

5 - Title

6 - Shelved separately

8 - Other scheme

Not supported on migration:

7 - Source specified in subfield $2

Item Barcodes

While Koha allows item barcodes to be duplicated, Alma does not. The item barcode must be unique in Alma, although it may be left blank.

The item barcode is migrated according to the following rules:

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.

Material Type

The material type in Alma is a description of the type of material the item is such as book, map, issue, DVD, compact disc, etc. It is controlled by a fixed list of physical resource material types in Alma. Each item in Alma must have a material type specified. The migration automatically assigns a material type on migration, based on the bibliographic record LDR and 007 fields. There is no customer input required for this part of the migration as the Alma types are fixed. The material type in migration is derived from the resource type which is constructed by Alma based on the bib header information. To see a description of how the resource type is determined, see the Resource Type Field description.

Areas/Fields Not In Scope

Boundwiths: We do not expect to receive items from Koha that are linked to multiple bibliographic records. If your library has cases where two or more bibliographic records are linked to the same item, consult your Ex Libris project manager.

Fulfillment

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 (CSV) format.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	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
pref_first_name	Alternate form of name. If at least one of these fields is filled and other(s) are empty, the empty field(s) are filled with the comparable regular name. For example, if you provide PREF_FIRST_NAME and PREF_LAST_NAME, but PREF_MIDDLE_NAME is empty, then the PREF_MIDDLE_NAME is filled with the value (if any) of MIDDLE_NAME. For more information, see Managing Users, search for the description for 'Preferred first / middle / last names'.
pref_middle_name
pref_last_name

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. The migration file validation tool does not provide a colon, but it does provide a space between the label and the value. See the explanation in the Migration Form mapping tab for UserStatCategories.

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.

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.

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. This is the only note which migration marks as user viewable.

Loans/Circ Transactions

Extract only current circulation transactions.

Provide the loan files in comma delimited CSV format. 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 CSV format. 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
borrowernumber	alphanumeric; this must be an identifier that is also present in the patron file.
date reserved	This value is placed in REQUEST_DATE, the date the request was made
priority	alphanumeric
barcode	alphanumeric
homebranch	alphanumeric
holdingbranch	alphanumeric
hold status	alphanumeric
not provided by Koha but requred	HOLD_DATE - date the item was placed on the hold shelf. Default: migration date
not provided by Koha but requred	EXPIRATION_DATE - date request expires. Default: migration date + 30 days

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.

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.

We have not seen any customer provide input for the type of fine/fee (example, overdueFine, LostItemReplacementFee, etc). Therefore, all fine/fees get the value assigned to the ALMAME_VAL_NOT_FOUND line in the migration form, Fine/Fee tab.

Provide the fine/fee files in comma delimited CSV format. 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

Customer Input - Fulfillment

Questionnaire Tab

Complete the following in the Questionnaire tab:

Enter a two-letter code for the default conversational language for your users

Code: PATRON_LANG

Default: en

Options: Use the two-letter codes as defined in ISO 639-1. Consult the codes from https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes. Additionally, the language code zh-tw (Taiwanese Mandarin) is accepted.

Which identifier should be used as the patron's Primary Identifier?

Code: PATRON_PRIMARYID

Default: UNIV ID

Options: Using the Koha Field Mapping Form, map the identifiers exported from Koha to the following list: UNIV ID, BARCODE, ADDL ID 1, ADDL ID 2, ADDL ID 3. Then, select the identifier to be used as primary for all patrons.

See also: Identification Numbers, Internal? Question on the User Group tab.

How should we handle duplicate identifiers in the same patron?

Code: DUP_ID_SAME_PATRON

Default: DISCARD

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

Default: DISCARD

Currency for patron fines

Code: CURRENCY

Default: USD

Options: Use the three-letter code (for example, USD, EUR, GBP) for the currency used for patron fines. For a list of valid codes, consult http://en.wikipedia.org/wiki/ISO_4217.

Merge Patron Prefix

Code: MERGE_PATRON_PREFIX

Default: No

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.

User Group Tab

The user group is used to distinguish groups of patrons from each other in determining different levels of circulation policies. Typical user groups are faculty, staff, and undergrad.

If patrons are being migrated, then this mapping table is mandatory.

Koha patron group: The incoming Koha patron group code, found in the patron group field of the patron extract.

Koha Description: A description of the Koha patron group, for informational purposes only. This column is not used in the mapping to Alma user group.

Alma User Group Code: The mapped group code in Alma. You can use the same codes that you used in Koha, or you can use different codes. You can also collapse groups if desired, for example, having Freshman and Sophomore from Koha both map to Undergrad in Alma. Do not use special characters, for example, slashes (/) or spaces in the code.

Alma User Group Description: The description of the Alma User Group. This description is loaded into the Alma code table as the description displayed in the user interface. This description can be changed easily after migration.

Internal? Y or N: Alma categorizes users as either external or internal. External patrons are managed and authenticated by an external system, such as through a regular load from the bursar’s office/campus student information system. Internal patrons are created and managed internally. Examples of internal patrons would be minority cases where community borrowers or alumni use library services. If you select Yes, all of the patrons in the Alma userGroup are categorized as internal. If you select No, all of the patrons in the Alma userGroup are categorized as external.

External users are fully external (except patron notes), including all user identifiers, authentication, and address information.

Notes/Comments: Add any notes or comments for the Koha User Profile. This column is not used during migration.

Further information: See also the following question in the Questionnaire tab:

Which identifier should be used as the patron's Primary Identifier?

See also the sections on internal/external patrons.

User Stat Categories Tab

This tab is used to migrate the statistical categories in your patron records (if you have them) to Alma. In many legacy ILS systems, it is possible to have multiple fields that contain statistical codes, usually named patron category or something similar.

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).

Incoming patron category: List all of the values from all of the fields that you want to put into the statistical category mapping. For example, if you listed three different three fields that have a patron category in the field mapping form, then list all of the values from all three of those fields here. Include the label applied if it is important to distinguish between values in different fields.

Source Description: A description of the individual categories, for information only. This field is not used in the mapping to Alma.

Alma Stat Category: The Alma Statistical Category code desired. This code is used to retrieve groups of patron records with various reporting tools.

Alma Stat Category Description: The description of the Alma Statistical Category Code. This value is loaded into the code table for userStatCategories. This description can be updated after migration.

Further Information: Alma has a Statistical Categories field in the patron record that can be used to retrieve statistics on groups of patrons.

Campus Code Tab

This mapping is not mandatory if you do not maintain separate patron campuses.

Koha patron campus: The value of the patron campus as found in the campus field of the patron extract.

Koha patron campus Description: A description of the location field, for informational purposes only. This column is not used in the mapping.

Alma Campus Code: The Alma campusCode desired. You may map the codes one-to-one, or you may use this map to collapse codes if desired.

Alma Campus Code Description: A description of the Alma campusCode, for informational purposes only.

Further Information: The Alma User Campus field is used to determine a patron’s affiliation for ILL or cross-campus borrowing. If your library maintains the location field in Koha for a similar purpose, map the location value to the Alma Campus Code value with this map.

Unlike other mapping tabs, the campus code and description are not loaded as a code table to Alma. Customers should set up campuses in Alma.

Fine Fee Type Tab

The Fine Fee Type indicates why a patron has to pay a fine. Some common examples are: Overdue material, Lost material, Registration fee.

Incoming Fine Fee Type: List all of the values from the corresponding field in the fine/fee extract.

Description: A description of the fine fee type, for assistance in filling out this form. This column is not used in the mapping routine.

Alma Fine Types: Possible values in Alma are listed in the drop-down list.

Further Information: Outstanding patron bills from Koha are migrated to Alma Fines and Fees. Only the currently owed amount is migrated. If any partial payments have been made before conversion, they are not reflected on migration to Alma.

Further Explanation – Fulfillment/Patrons

Internal/External Patrons

Alma categorizes users as either external or internal. External patrons are managed by an external system, such as through a regular load from the bursar’s office/campus student information system. Internal patrons are created and managed internally. Examples of internal patrons are community borrowers or alumni. Use one of the following two ways to define a patron as internal or external:

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.

Identification Numbers

The migration program allows for six different types of user identifiers: University ID, Barcode, and Additional ID 1, 2, 3, and 4. Select one of these identifier types as the primary ID – the primary unique identifier for the patron. You may map multiple identifiers from your previous ILS. You may also consider mapping email address, a common matchpoint in authentication systems, to an additional ID field.

Use the User Identifier section in the Koha Field Mapping Form to map a local Koha identifier to the Alma expected identifier types. Then, select an Alma identifier type to be the Primary ID using the PATRON_PRIMARYID question on the Questionnaire tab.

When selecting the primary ID, the first identifier found in the field is used as the primary ID, and all subsequent identifiers are kept in the userIdentifier section. The primary ID must be unique, so if there are duplicates, the first unique ID found is migrated as is, and the IDs for the second and subsequent patrons with the same ID are given a suffix of -1, -2, etc.

Identifiers may not be duplicated, even within the same patron record. See the questionnaire question DUP_ID_SAME_PATRON for options.

If the identifier selected for the primary ID is not present, the migration program creates an identifier for the patron based on the patron original ID, prefixed with ID. The migration programs do not fill in the primary ID with a non-selected identifier.

Select BARCODE, UNIV_ID or ADDL ID 1, 2, 3, or 4 as the primary ID type for all patrons in the Questionnaire tab of the Koha Migration Form.

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.

Customer Input

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.

Questionnaire Tab

ACQ mode

Code: ACQ_MODE

Options: Select Yes or No depending on whether or not you have contracted with Ex Libris to migrate any Acquisitions data.

What is your currency?

Code: ACQ_CURRENCY

Default: USD

Options: List the currency used for all of your funds. Orders can have other currencies and be translated to the default currency, but funds must have a single base currency.

The currency should be a three-letter code, as listed in http://en.wikipedia.org/wiki/ISO_4217

Fiscal Period Cycle Pattern

Code: FISCAL_PERIOD

Default: 01-07-1 (fiscal period starts on July 1 (01-07) and lasts for one year (-1).

Options: To have functioning ledgers, fiscal periods are required. Specify your fiscal period as DD-MM-C (Day-Month-Cycle). For example, a one year fiscal period starting on January 1 is indicated by: 01-01-1. A one year fiscal period starting on July 1 is indicated by: 01-07-1.

Alma currently supports one-year fiscal period cycles.

Which year do you use to name the fiscal year?

Code: FISCAL_PERIOD_NAME

Default: second

Options: Specify if the fiscal period is named with the first year or the second 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.

If your fiscal period runs from January 1 through December 31, this question is not necessary.

Current Fiscal Year

Code: CURRENT_FISCAL_PERIOD

Default: determine by date of conversion

Options: This question is important around the fiscal period close, depending on whether or not you have run fiscal period close in your legacy ILS or if you will run it in Alma after migration. If you do not know how to answer this, select determine by date of conversion. The options are:

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

In Koha, all resources are categorized as physical in the database, even if the record represents an electronic item. All records are converted to Alma as physical initially. A second process converts records identified as electronic to the electronic format. You provide a list of records that are identified as being electronic, as part of the data delivery, in the following format:

123475,portfolio

12346,DB

The words portfolio and db are not case-sensitive; therefore, both portfolio and Portfolio are acceptable.

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.

Customer Input

Questionnaire Tab

For each of the following three questions (P2E_LINK, P2E_NOTE, and P2E_PROVIDER), you can use indicators in the following manner:

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.

Which Holding or Bib field stores electronic link information

Code: P2E_LINK

Options: Provide a 3 digit MARC field code + subfield: 856u. Only one subfield is allowed.

Recommendation: 856 u

Default: If this is left empty, no tag is used.

Which Holding or Bib field stores electronic link public note

Code: P2E_NOTE

Options: Provide a 3 digit MARC field code + subfield: 856z. Only one subfield is allowed.

Recommendation: 856 z

Default: If this is left empty, no tag is used.

Which Holding or Bib field stores electronic provider name information

Code: P2E_PROVIDER

Options: Provide a 3 digit MARC field code + subfield: 856m. Only one subfield is allowed.

Recommendation: 856 m

Default: If this is left empty, no tag is used.

Alma Location Tab

Electronic Location Column

Identify which locations indicate an electronic holding or item record. A single bibliographic record may contain holdings for multiple locations, but only the holdings/items for electronic locations need to be identified. Identify the locations in the in the Electronic Location? column in the Alma Location tab of the Koha Migration Form.

Further Information

If you have multiple 856 links in a single bibliographic record identified as electronic, a different inventory link for that bibliographic record is created for each URL found in the record. In addition, if you have two item records with different electronic locations attached to the same bibliographic record, a different inventory link is created for each location, as well.

For more information on the electronic migration approach to Alma, refer to Electronic Resource Handling in Alma Migration.

Appendix A – 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.

Appendix B – Post-Migration Process Statuses

The process statuses (codes) from Koha are mapped to the indexed internal note 3 field of the Alma item. These items are considered not available after migration when process = Technical – Migration.

These fields are currently indexed in the item keyword and advanced searches.

When searching for physical items, a staff user can search by item process status code with the general keyword search and then by facet if before searching, Process type = Technical – Migration and with the advanced search filter when Process type = Technical – Migration.

In order to give items

real Alma statuses or remove the Technical – Migration status, scan the barcode of the item to various configured departments (via receiving, for example), request a move to various departments/temp locations, or just scan the item for return, which removes the status from the item.

You can also use the Scan In API, described here: https://developers.exlibrisgroup.com...le-of-barcodes.

Additionally, it is also possible to configure the GetIt (Primo) services to display or not display items with this process status in the GetIt Item list.

Migration Overview

Recommendations for Using this Guide

Related Documentation

Requested Files from Koha

Koha Field Mapping Form

Koha Delivered Files Form

Inventory

Bibliographic Records

Suppressed Records

Holding records

Non-MARC Serial Holdings

Holdings From a Bib Tag

Call Number from Bib tag (special processing)

Items/Holdings

Secondary Item File

Customer Input - Inventory

Questionnaire Tab

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?

Internal record designation for Linked Entry fields $w

Indicate which 852 subfields to use to determine unique holding records

Do you want to use a call number in the generated holdings records?

Move 852$c to Another Subfield

Limit exported records by location

Bib Key Prefix

Move 001/003 to 035 or 935

Add institution suffix to Bib ID

Use subfield indicators in item call number (AltCallNo)

Add $9 LOCAL to specified tags

Alma Library Tab

Alma Location Tab

ALMAME_VALUE_NOT_FOUND

Alma Location Name and Alma External Location Name

Collapsing Locations

Item Type Tab

Item Base Status Tab

Material Type Tab

Shelving Scheme Tab

Further Explanation – Inventory

Bibliographic Records

Determining Groups for Holding Record Creation/Matching

Changing the Holding Record Grouping/Matching

Call Number Type

Item Barcodes

Material Type

Areas/Fields Not In Scope

Fulfillment

Patrons

User Identifiers

User Preferred Address

User Statistical Categories

Notes

Loans/Circ Transactions

Requests/Holds

Separate Fine/Fee File

Customer Input - Fulfillment

Questionnaire Tab

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?

Currency for patron fines

Merge Patron Prefix

User Group Tab

User Stat Categories Tab

Campus Code Tab

Fine Fee Type Tab

Further Explanation – Fulfillment/Patrons

Internal/External Patrons

Identification Numbers

Acquisitions

Customer Input

Questionnaire Tab

ACQ mode

What is your currency?

Fiscal Period Cycle Pattern

Which year do you use to name the fiscal year?

Current Fiscal Year

Physical to Electronic (P2E) Processing