Skip to main content
ExLibris
  • Subscribe by RSS
  • Ex Libris Knowledge Center

    TLC to Alma Data Delivery Specifications

    This migration document is intended to be used by customers who are coming from the Library Solution integrated library system, produced by The Library Corporation. This library system is typically referred to as TLC (for The Library Corporation), so this document uses TLC throughout.
    Customers are expected to provide extracts for their inventory and fulfillment data, and map them into expected TLC fields using this guide and the TLC Field Mapping form.
    The procedure for migrating from TLC to Ex Libris’ Alma consists of the following steps:
    1. Indicate which local fields correspond to Ex Libris' expected fields using the TLC Field Mapping form, prior to data delivery (customer responsibility).
    2. Validate the flat files using Non-Ex Libris to Alma Validation Tool Excel. It is recommended that this step be done against a small sub-set of data to ensure that the header of each of your flat files and the filled in TLC Field Mapping form match each other.
    3. Extract the relevant data elements from the ILS into flat files (customer responsibility).
    4. Upload the files to Ex Libris’ secure file server (MFT) along with the TLC Delivered FIles List form and the executed/validated Non-Ex Libris to Alma Validation Tool (customer responsibility).
    5. Transform the data elements, based on the Field Mapping form, into an intermediate conversion XML format (Ex Libris responsibility).
    6. Load the transformed data into Alma (Ex Libris responsibility).
    Deliver the TLC Field Mapping form and validated data validation output form to Ex Libris along with the TLC Migration Form prior to the actual delivery of the data. The lead time depends on your project schedule. Provide the TLC Delivered Files form, which lists the file names and the record counts for each file, at the same time that you provide your data extract files.
    Provide the data elements in flat files, and place them on an Ex Libris secure file server (MFT). Prepare the data files in the exact format as specified in Appendix A – File Delivery and Delivered Files Form with the naming conventions as described there.

    Files Requested from TLC

    Ex Libris expects a certain set of files to be exported from TLC, listed below. As files are extracted, be sure that the extracted file description, such as data elements and lengths, matches the description in Expected File Formats.
    The data elements listed are those that Ex Libris expects to use in conversion. Not all data elements that exist in the local ILS are necessary to transfer to Alma.
    The scope of your specific conversion is agreed upon in your Alma contract.
    • As you extract data from any area listed below, provide it to Ex Libris via a secure file connection (MFT). This facilitates the transformation analysis and expedites the conversion process. For file delivery instructions, see Appendix A – File Delivery and Delivered Files Form.
    • DO NOT OPEN/UPDATE any delimited file extracts you provide to Ex Libris in Excel. This may ruin the appropriate delimiter formatting and text formatting and may result in corrupted data.

    Expected File Formats

    All the files listed in the tables below are expected in CSV format with one record per line, and fields delimited by commas and multi-values within fields delimited by semicolons. The following is an example of a record with multiple values for the third field:
    “field1”,”field2”,”field3a”;”field3b”,”field4”
    The following are the only exceptions to this expected format:
    • Bibliographic records (which are MARC standard files) - this includes items which are embedded in bibs
    • MARC Holdings records

    For all files, the maximum file size is 2GB.

    TLC Field Mapping Form

    Prior to submitting your extracted files, complete the TLC 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 field names and how they map to Alma's expected field names.
    On all of the tabs in the TLC Field Mapping form, there is a ##Foreign Key## column. Customers should not fill out this column – it is for internal use only. In addition, there are various note fields for each data element. Fields that are not expected by Ex Libris (because there is no functional place for the data element in the corresponding Alma data structure) can be placed in a note in the record. Specify the note type that you want the field to go to at the bottom of each tab in the TLC Field Mapping form.

    TLC Delivered Files Form

    At the time you submit the requested data files, submit the completed Excel spreadsheet TLC Delivered Files form. List the files, record counts, and encoding for each file delivered to the MFT server.

    Inventory

    Bibliographic Records

    Bibliographic records are expected in MARC, UNIMARC or KORMARC format. Binary MARC, UNIMARC or KORMARC is preferred, but Ex Libris also accepts files in MARCXML, UNIMARCXML or KORMARCXMLformat as well. The character encoding expected is UTF-8 or ANSEL/MARC8. If your library prefers to export in a different format, inform your Ex Libris project manager. All files should be delivered with the same character encoding.
    Each Bibliographic record MUST have a single unique source key/identifier in a consistent single source MARC/UNIMARC/KORMARC field. Records which do not conform will be rejected.
    The following sections explain additional bibliographic use-cases which are supported.

    Suppressed Records

    Suppressed records are those bibliographic records that you want to have in the database, but not show to the public. Examples of this are:
    • titles on order
    • missing or damaged titles where you want to keep the record but not show it to the public
    • titles that are for internal management only, such as equipment
    Provide a text file that contains the source BIB key/ID, one key per line, for bibliographic records that are suppressed.

    Boundwiths

    Ex Libris does not expect to receive boundwith information from TLC customers.  However, if you think you have boundwith info, contact your Ex Libris project representative.  A boundwith is where a single item is linked to multiple bibliographic records. 
    Examples of boundwiths:
    • Bound journals with a title change in the middle of the year. For example, if January – April is “Journal of Mathematics Education” and May – December is “Mathematics Educator”, and all 12 of the issues are bound in the same volume with a single barcode.
    • Pamphlets or small volumes with similar content which were combined into the same item/barcode, either by binding or in a folder.

    Linked Bibliographic Records

    If you use standard 7XX fields for linking between MARC/KORMARC bibliographic records (or standard linking fields for UNIMARC), they are leveraged during migration and create appropriate bibliographic-level linking in Alma.
    No exported files are necessary for this category: use the migration form, Questionnaire tab, to indicate if your bibliographic records contain linking fields.

    Electronic Link Resolver Records

    If you have SFX MARCIt records or equivalent electronic records in your ILS that are also represented by your link resolver system, it is suggested that they be excluded from the data provided to Ex Libris to avoid unnecessary duplication with the link resolver system data. If these records are NOT removed, you will likely see a record in Alma migrated from the ILS and the same record migrated from SFX.
    An exception to this is if the records have active orders or physical inventory that are also being migrated, these records should be kept. If you choose to provide a string to indicate records to be removed/not migrated, the migration programs remove records with no attached orders or inventory and keep records with attached orders and items.
    No exported files are necessary for this category: use the Questionnaire tab of the migration form to indicate a string that will be checked in the 035 field. Example: ‘(SFX)’.

    Holding Records

    Ex Libris does not expect to receive MARC holding records or non-MARC serial holding records from TLC customers.
    Holding records can be generated from a summary statement in the bib record, as described below.  If no holding record is present for an item, the migration program generates a holding record based on information in the item.  See the 852_subfields_for_hol section in the migration guide for more information about how to determine how item records can be grouped when generating holding records.

    Holding Records from a Summary Statement in a Bibliographic Record

    If the customer has serial holdings which are only represented by a summary statement such as Vol. 1 (1980) – Vol. 21 (2000), these statements should be included in a tag in the bibliographic record. Use the Holdings tab of the TLC Field Mapping form to indicate which field and subfield contents to use for generating holdings records from summary statements embedded in the bibliographic record.
    Fill in the values of the following fields in the Holdings tab of the TLC Field Mapping form. If the SUMM_LOC_CODE matches an existing holdings record on the same bibliographic record, even a holdings record that was generated from items attached to the same holdings record, then the summary holdings statement is attached to that holdings record, regardless of call number. In other words, the summary holdings is placed on the holdings record with the same 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.
    Holding Records from a Summary Statement in a Bibliographic Record
    Expected Field Name Value Notes
    SUMM_TAG   Five characters; tag+2 indicators. May use # as wildcard, for example, 866##
    SUMM_SUBFIELDS   Multiple subfields allowed,for example, 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 (such as a) that 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   Public note, is placed in 852 $z of the generated holding record.
    SUMM_NON_PUBLIC_NOTE_SUBF   Non-public note, is placed in 852 $x of the generated holding record.

    Item Records

    Ex Libris expects item records from TLC in item fields which are embedded in bibliographic tags in the BIB extract.  This is typically in the 949 tag of the bib record but can be in any tag that you specify.  Indicate the tag (for example, 949) that contains the embedded item.
    Then, place the subfield code in the TLC Field Mapping form in the appropriate field, for example:
    LIBRARY $m
    LOCATION $n
    ITEM_CALL_NO $c

    Item Record

    The following subfields are expected in the item tag.  
    Dates can be in any format, but they must be consistent. Do not use YYYYMMDD and then MMDDYYYY in the same file.
    Item Record
    Expected Field Name Notes
    $g barcode will be used in loan, request, and fine/fee files to link to the relevant item
    $a Library use in the ALma Location tab if customer uses two levels of location. This is the higher level of location.
    $b Location use in the Alma Location tab. If customer uses only one level of location, use this field for that single level of location. Use column B in the Alma Migration Form, Alma Location Map for this single location.
    $c Call Number  
    $d Call Number second part  
    $k call number prefix  
    $m call number suffix  
    $h description date part  
    $i description enumeration part  
    $n copy number  
    REPLACEMENT_COST Place a field here ONLY IF this will be used an actual replacement cost for a lost item in Fulfillment.
    INVENTORY_PRICE Place a field here for information purposes about the original cost of the item.
    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
    PUBLIC_NOTE Shows to the public
    FULFILMENT_NOTE Pops up at circulation activity.
    NON_PUBLIC_NOTE_1 Internal notes
    NON_PUBLIC_NOTE_2  
    NON_PUBLIC_NOTE_3  
    STAT_NOTE_1 Statistical notes
    STAT_NOTE_2  
    STAT_NOTE_3  

    Suppressed Item Records

    All suppressed item records are migrated to Alma as regular items (not suppressed). However, specific locations can be marked as suppressed in Alma so that groups of items can be suppressed from public view

    E-Resources Indication (P2E)

    Provide a list of bibliographic system numbers that represent electronic resources and an indication if these electronic resources are portfolios, packages, or database resources. Prepare the list as a comma separated text file containing lines that represent each e-resource. Structure each line as follows:
    <bibnumber>,<resource type>
    For example:
    000000001,Portfolio
    000000002,DB
    During the P2E process, all resources must either be categorized as a portfolio or a database (DB).  It is not possible to generate packages during P2E processing, since packages require at least one portfolio.   A database is essentially a zero-title package.  Post migration, when you add portfolios to the db, you can change them to type 'package'.
    Note that the words portfolio  and db are not case-sensitive, therefore both portfolio and Portfolio are acceptable.

    Fulfillment

    Patrons

    Ex Libris expects patron records in CSV delimited format. Patron records without a record key identifier are skipped, since this is the minimum required patron information. The record key identifier is used to link the patron to other records such as loans, requests, and fines.
    The following fields are expected. Indicate the local field names for the expected fields in the Patrons tab of the TLC Field Mapping form.
    Patrons
    Field Name Notes
    Borrower Name use PATRON_NAME_ORDER on the questionnaire tab to tell us if this is 'First Last' or 'Last, First'
    Borrower ID  
    Borrower Type  
    Card Expiration Date if empty, migration fills in conversion date + 1 year
    Date of Birth  
    Account Status  

    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. Enter fields from your institution’s patron extract that include identifiers. The values in the left column cannot be changed, but the fields in the right column may be modified/rearranged/added to. Use the values in the left column to select the appropriate primary identifier in the Questionnaire tab of the TLC Migration Form, PATRON_PRIMARYID question. 
    All patron primary identifiers MUST be unique across all users, as required by Alma. If they are not, the migration program disambiguates them.
    User Identifiers
    Alma Identifier Type Typical TLC fields
    UNIV_ID Alternate ID
    BAR Borrower ID
    ADDL_ID_1  
    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 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 a type for each address, phone, or email. All can be selected so that the address, phone, or email can be used as any type.
    User Preferred Address
    Address Field Repeatable? Instructions
    ADDRESS_LINE_1 Y  
    ADDRESS_LINE_2 Y  
    ADDRESS_LINE_3 Y  
    ADDRESS_LINE_4 Y  
    ADDRESS_LINE_5 Y  
    ADDRESS_CITY Y If city, state, zip and country are all together on one line, you can put them into one of the ADDRESS_LINE_x fields
    ADDRESS_STATE Y  
    ADDRESS_CODE Y Postal code
    ADDRESS_COUNTRY Y Migration programs make no attempt to standardize this country name/code.  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 Y  
    ADDRESS_START Y Date
    ADDRESS_END Y Date
    ADDRESS_TYPE Y Select one: HOME, WORK, SCHOOL, ALTERNATIVE, ALL
    PHONE Y  
    PHONE_TYPE Y Select one: Home, Mobile, Office, OfficeFax, All
    EMAIL Y  
    EMAIL_TYPE Y Select one: Personal, School, Work, All

    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 User Group, but you may want to track the department, so that you can get more detailed statistics on how Law students borrow, for example. Since various ILS systems have different fields for tracking statistical categories, we provide you the option to map the data from any field in TLC to the User Statistical Categories in Alma. 
    User Statistical Categories
    User Statistical Category Local Field Name Field Label
    USER_STAT_CATEGORY   DEPT:
    USER_STAT_CATEGORY   SCHOOL:
    USER_STAT_CATEGORY    
    Up to 10 incoming fields can be mapped. To map the values, use the UserStatCategories map in the TLC Migration Form. If a value is not found in the map, it is migrated as is. If you use a label, the userStatCategory map expects the incoming field to include the label. The first column in the userStatCategory map would be: LABEL:value, for example if you put 'SCHOOL:' in the Field Label column, and the incoming category was law, then the expected incoming mapping value is: SCHOOL:Law.  This is implemented in case there are multiple categories with 'Law' as the value. Example SCHOOL:Law and MAJOR:Law.  You may wish to map these differently in the mapping table. The migration program does not include the colon so if you want it, then include it in the label as above.

    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.
    Notes
    Note Name Information
    LIBRARY_NOTE  
    BARCODE_NOTE  
    ADDRESS_NOTE  
    OTHER_NOTE OTHER_NOTE is set to User Viewable by the migration programs

    Loans/Circ Transactions

    Extract only current circulation transactions - items that are currently checked out.  Alma does not migrate historical circulation transactions.
    Provide the loan files in comma delimited format. The following fields are expected. Use the Loans tab of the TLC Field Mapping form to indicate local field names for the expected fields.
    Loans/Circ Transactions
    Field Name Notes
    Borrower ID links to borrower ID in patron file
    Item Barcode links to item barcode in embedded item tag
    Date Checked Out if no field is present, will use conversion date as the checkout 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  

    Requests/Holds

    Ex Libris does not expect to receive hold request information from TLC customers.  If you think you have hold request information, contact your Ex Libris project representative.

    Fines/Fees

    Fine and fees information is not mandatory, but when it is provided, Ex Libris expects active fine and fee information in csv format (preferably as an outstanding active balance total in the patron CSV extract). Only active (outstanding) fine and fee information is migrated, and only the outstanding balance of each individual fine/fee; partial payment information is not preserved. The following fields are expected. Indicate the local field names for the expected fields in the Fines/Fees tab of the TLC Field Mapping form.
    Field Name Notes
    BARCODE links to Borrower ID in patron file
    LOCATION  
    Item Barcode matches item barcode from embedded tag in bib
    Fine Details use in Fine Fee Type map in Migration Form
    Fine Date  
    Fine Amount*  
    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  

    Acquisitions

    Ex Libris does not expect to receive Acquisitions information from TLC customers.

    Appendix A – File Delivery and Delivered Files Form

    Place any data files that you provide to Ex Libris in the formats indicated in Expected File Formats on a secure file drop-point on the Ex Libris MFT server. Use the access credentials provided by your Ex Libris project manager to connect to the server.
    The following is the default naming convention:
    CustomerName+DataType+sequence+date+[.<file_extension>].</file_extension>
    For example: centralu_bib_01_20120420.mrc, centralu_bib_02_20120420.mrc, centralu_bib_03_20120420.mrc
    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. For example, do not delimit with quotes and commas for some records and pipes for others within the same file.
    Provide the TLC Delivered Files List form along with the submitted files.
    • Was this article helpful?