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

    Ares to Leganto Migration Guide

    This migration document is intended to be used by customers who are moving from the Ares Course management system to Leganto.
    This document serves three purposes:
    • A step-by-step guide to filling out the Ares to Leganto Migration Form
    • A description of data elements expected, and how they are mapped using the Ares to Leganto Migration Form.
    • An explanation of general migration rules which do not require any customer input

    Recommendations for Using this Guide 

    This document is divided into two areas:

    • Courses
    • Reading Lists

    Each area has the following sections:

    • File Information: Information on files that are expected from Ares and where incoming fields are mapped in Leganto, including functional implications.  
    • Migration Form: Questionnaire Tab – Instructions for individual questions asked on the Questionnaire tab of the Migration Form.
    • Migration Form: Individual Tabs – Instructions for how to fill out individual tabs on the Migration Form. 

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

    For more information about any of the data input or about the migration in general, see the more detailed explanations in the Further Explanations sections.

    Related Documentation 

    • This document is intended to complement the Ares to Leganto Migration form - an Excel spreadsheet that is read by the migration programs. It provides further information regarding the migration process and the steps required for migration to Alma.
    • Prerequisites: Basic knowledge of Alma and Leganto key concepts and architecture. You may also wish to consult the Leganto documentation.

    Migration Overview

    The procedure for migrating from Ares to Leganto consists of the following steps:
    1. Export Course and Reading Lists from Ares (customer responsibility)
    2. Indicate which local fields correspond to the Leganto expected fields using the Course and Reading List tabs of the Ares to Leganto Migration Form (customer responsibility).
    3. Complete the Ares to Leganto Migration Form.
    4. Upload the files to Ex Libris’ secure file server (MFT) along with the completed Ares to Leganto (customer responsibility). 
    5. Transform the data elements, based on the Field Mapping form, into an intermediate tab-delimited format (Ex Libris migration team responsibility).
    6. Load the transformed data into Leganto (Ex Libris Professional Services responsibility).
    Provide the data elements in flat csv files, and place them on an Ex Libris secure file server. Prepare the data files in the exact format as specified in Appendix C – File Delivery and Delivered Files Form with the naming conventions as described there.  List the delivered files on the Questionnaire tab of the migration form.
    The Migration team transforms incoming files into the expected file formats detailed in the Leganto documentation: Course Loader and Reading List Loader.  The loading of the data (test and cutover) is performed by Ex Libris project staff.

    General Format of incoming files

    The incoming files should be in CSV (quotes/commas) format, as they are exported from Ares.   Please ensure that there are no linebreaks within the data, for example sometimes there are notes with carriage returns, which make the entire line unreadable.


    Course files should be delivered in csv format (quotes and commas).  

    Let Ex Libris know how to map your incoming fields using the 'COURSE field mapping' tab on the ARES to Leganto Migration Form.  The following fields are expected from ARES:

    Expected Field Name Notes
    Course ID This is ONLY needed to link to Reading List/items.  This is an internal ARES key which is only used for linking, and will not be loaded into Alma/Leganto.
    Name Course Title; this is mandatory.  This is also placed in the Reading List Name field.
    Course Code

    This is mandatory; either use Course Code field or something else like External Course Id.  This is the primary unique key for courses in Alma/Leganto.  

    This field will be placed in the 'to be loaded' Reading list file, so that this code can be used as the link between course and reading list.

    Semester Use the Term Mapping tab to transform this to the Terms code table
    Year If you wish to use the first four digits of the 'Semester' tab to go into 'Year', put 'Semester' here.
    Section There is no incoming field called 'Section'.  You may choose to put another field here
    Start Date In date format specified
    Stop Date In date format specified
    Department Use the Academic Dept tab to transform this to the Academic Department code table
    Instructor Must be an Alma Primary ID; provide external file if necessary.  See External Files section below.
    Default Pickup Site Use the Processing Dept tab to transform this to the Processing Department code table
    Course Enrollment Integer
    External Course Id (search ID 1) If this is not supplied in the file, you can provide an external file which maps from Course Code.  This is placed in Search ID1.  See External Files section below.
    Search ID 2 You may choose any field to put in search ID2.

    Items (Reading List )

    The incoming item file should be provided in CSV format (quotes/commas).   This is transformed to the ALma reading list.

    Let us know how to map the incoming fields to the Leganto format using the 'ITEM field mapping' tab of the ARES to Leganto Migration Form.  The following fields are expected from ARES: 

    Expected Field Name Notes
    Course ID

    needed to link to course file.  This is an internal ARES key and the only thing it is used for is linking to the course file.  It is not loaded into in Alma.

    For the 'to be loaded' Reading List file, this is not sued.  The actual 'Course Code' is going to be used to link between the course and reading list files for load.

    Item ID Original system ID from ARES (not an Alma ID)
    Processing Location use in RL Assigned To tab, to map to an Alma patron ID
    Location If this contains http, then this is put in creation source.  If a file, then there should be an external file for loading
    Copyright Required use in Creative Commons mapping tab
    Copyright Obtained use in Creative Commons mapping tab
    Pub Place  
    Pub Date  
    Cited In  
    Article Title  
    Item Format use in Citation Material Type map
    CCC Number  
    Item Barcode If desired, provide an "Item Barcode to MMSid" map.  If an external map is not provided, no attempt is made to link to an Alma MMS record.  See External Files section below.
    Item Info1  
    Section this is not an ARES field but you can place something here if desired, if you want the 'Section' field in Leganto to be filled.
    Semester used as part of the reading list code
    Start Date  
    Stop Date  
    Instructor Tags will be placed in citation instructor note

    Optional Note fields

    The following fields are notes or note-like.  You can place any incoming field in the following expected fields.

    Expected Field Name Notes
    citation_tags Tags must already be defined in Alma
    citation_note Migration already puts two things here: Item Info, and Article Title if this is a Book.

    External Files

    In order to successfully match Ares data with Alma data or other systems, you may provide external maps, for both course and reading list.

    External Course ID (for course file)

    If you have an external course ID, you can provide a map of Ares Course Code -> External Course ID.  For example, you might have an identifier for the course in an external campus system, and you may want to use that code to link to this external system.

    The mapping file should be simple, like: 


    Instructor (for course file)

    In order to link courses to instructors, the file to be loaded must have an identifier associated with an Alma user.  The string of the instructor's name is not enough for a match. The map for the instructor to Alma user identifier should be placed in the Migration form, 'Instructor' tab.

    For help on retrieving a list of identifiers, see Appendix B - Instructor to Primary ID.

    Item Barcode -> Alma MMSID (for Reading List file)

    If you have an item barcode in the reading list file, you can use Alma Analytics to retrieve the Alma MMSID.  The link between reading list and Alma inventory is via the MMSID, not through the item.  Provide this file as a simple external CSV file, with two columns:

    Item Barcode,MMSID

    For help on retrieving a list of MMSIDs based on a list of barcodes, see Appendix C - Barcode to MMSID.

    Migration Form

    Questionnaire tab

    Institution Code, Customer Code, Institution Name, Customer Name

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

    INST_NAME and CUST_NAME: These are informational.

    Incoming Date Format for ARES


    Default: yyyyMMdd

    Options: List the date format for the incoming date from ARES. MM = two digit month, dd = two digit day, yy or yyyy = year.  Examples: yyyyMMdd, MM/dd/yyyy

    Date Format as Listed on Integration Profile in Alma


    Default: yyyyMMdd

    Further Information: On the Alma/Leganto Integration Profiles used to load courses and reading lists, there is a line for 'Date Format'.  List that date format here. MM = two digit month, dd = two digit day, yy or yyyy = year.  Examples: yyyyMMdd, MM/dd/yyyy

    FYI, your Ex Libris representative will help you set up this integration profile.

    To see the integration profiles, go here: Alma Configuration Menu –> General –> External Systems –> Integration Profile.  Integration Type = 'Course Loader'

    Reading List Visibility


    Default: PUBLIC


    Further information: Select the default visibility for all of the reading lists.   This is also known as the Publication Status, and more information can be found on the Managing Reading Lists page.

    Limit the Migration to only recent courses


    Default: N/A, this is not mandatory

    Options: Type a four-digit year (e.g. 2021), and the migration will migrate courses for 2021, 2022, 2023, 2024 etc.  The migration checks the first four digits of the 'Semester' field.


    Use this tab to map incoming 'Semester' column to an Alma Term. This field is mandatory, so an ALMAME_VAL_NOT_FOUND line is required.

    Incoming Semester: Semester field from the Course extract.  Usually in the format yyyyMM, like '202301'

    Description: a description of the incoming field, for note purposes and not used in the map/migration

    Alma Term code: A dropdown list of available term codes in Alma.

    Alma Term Description:  You must use the existing list of Leganto term codes, but you can use whatever name you wish.  The Description associated with the first instance of the code will be loaded to Alma.

    Academic Department 

    Use this tab to map the incoming 'Department' field to the Alma 'Academic Department'.  Columns C and D from this tab are used to generate the Alma code table for Academic Departments. This field is mandatory, so an ALMAME_VAL_NOT_FOUND line is required.

    Incoming Department: 'Department' field from the Course extract.  

    Description: a description of the incoming field, for note purposes and not used in the map/migration

    Alma Academic Department code: A code for the academic department.

    Alma Academic Department Description: The description for the academic department.

    Further information: For more information see the help guide for Academic Departments.

    Processing Department

    Use this tab to map the incoming 'Default Pickup Site' to the Alma 'Processing Department'. This tab is NOT used to load anything into Alma, this is a map only.  This is mandatory so an ALMAME_VAL_NOT_FOUND line is required.

    Incoming Default Pickup Site: 'Default Pickup Site' field from the Course extract.  

    Description: a description of the incoming field, for note purposes and not used in the map/migration

    Alma Processing Department: A code for the processing department.

    Further information: For more information see the help guide for Processing Departments.

    RL Assigned To

    Use this tab to map the incoming 'Processing Location' to an Alma staff user account, by providing the user's Primary ID.  This is not mandatory, if nothing is assigned, then it shows up on the 'Unassigned' tab.

    Incoming Processing Location: The 'Processing Location' field from the Reading List input file.

    Description: a description of the incoming field, for note purposes and not used in the map/migration

    Alma Primary ID for Reading List assignment: The primary ID of an Alma staff user, for reading list assignment.

    Creative Commons

    Use this tab to map the incoming copyright fields to an Alma Creative Commons value.  This field is not mandatory, so ALMAME_VAL_NOT_FOUND is not required here.

    Incoming fields: The two incoming fields for this map are: 'Copyright required' and 'Copyright obtained'.   They are both TRUE/FALSE.

    Alma Creative Commons value: The list of possible creative commons values are listed in the dropdown for this column.

    Further information: for more information on copyright in Leganto, see Configuring Leganto Copyright-related Procedures.

    Citation Material Type

    Use this tab to map the incoming Ares reading list item format to a citation type in Alma/Leganto.  This field is mandatory, so the ALMAME_VAL_NOT_FOUND is required.

    Incoming Item Format: The value from the 'Item Format' field in Ares.

    Description: a description of the incoming field, for note purposes and not used in the map/migration

    Alma Citation Material Type: The column in the spreadsheet contains a dropdown of possible values for this field.   

    Be aware that the mapped value here is used to determine if the Alma/Leganto field 'Citation Chapter Title' contains the Ares field 'Title' or 'Article Title': 

    If Item Format (mapped) = BK or CR then try to fill in Citation Chapter TItle.  First, use Article Title.  If Article Title is blank then use Title anyway.  If both 'Title' and 'Article Title' are blank (and it's BK or CR) then say ‘Unknown Title’.

    Instructor Map

    The instructor map should contain two text columns.

    Column A: the text in the 'Instructor' field in the incoming course file

    Column B: an identifier from Alma which represents this instructor

    For instructions on how to retrieve an identifier given a string, see the Instructor section in "External Files" above. 

    Appendix A – Delivering Files 

    Place any data files that you provide to Ex Libris in the formats indicated in Expected File Formats on the MFT server which has been specified to you by your Ex Libris project manager. 
    The following is the default naming convention:
    For example: centralu_course_01_20240420.csv, centralu_course_02_20240420.csv, centralu_course_03_20240420.csv
    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 semicolons for others within the same file.

    Appendix B - Instructor to Primary ID

    Alma requires an Instructor's Alma Primary ID to link an instructor to a Course.

    Ares default course information includes Instructor name(s) and Instructor Display Name. An optional (recommended) field to include is a "Created by" identifier in the course extract.

    Usually none of the values is the Alma Primary ID, so a mapping from the Ares value to Alma Primary id is needed for the Instructor tab on the migration form.  The following are the suggested steps for creating such a map.

    First, Create a Unique List of Instructors.
    1. Work from a copy of your exported Courses file from Ares.

    2. Select the Migration Form field for 'Instructor' in the Courses file.  Determine which field of those included in the Courses extract (Instructor Name, Instructor Display Name, or Created by) is most accurate.  This is the field you should include in the Migration form as your "Instructor".

    3. Create a unique list (deduplicated) of chosen 'Instructor' values and their ARES unique identifier (possibly Created By ID). Identifier could be Alma Primary Id, any Identifier or email address.  This may require programming/reports from ARES or another system to link Instructor names to an identifier which is in Alma.  If this unique list's identifier is also their Alma Primary ID, skip to the last step of adding this information to the Migration form, instructor tab.

    4. In Alma, use the Ares unique ID provided and Analytics to 'lookup' the Primary ID.  Below is one possible method:

    Alma Analytics Suggested steps 

    If you already have the Alma Primary ID, these steps are not needed.

    a. In the saved unique list of Instructors and IDs, sort by the IDs
    b. Dedup the IDs - You may wish to group the IDs into sections of a few hundred for extract from Analytics.  You will be copying/pasting into Analytics.
    c. Go to Alma > Analytics > Access Analytics
    d. Create > Analysis > Subject Area > Users
    e. Add User Details > First and Last Name; Full Name; Identifiers > Identifier Type and Value; Email > email (Only add necessary
    f. Add Identifier: Identifier type and Identifier value > filter this type to match the type of identifier provided in the Unique List
    g. Add Email: email field - only if email was the ID provided in the Unique List 
    h. Filter the Idenfier or Email value field "is in"
    i. Per
    edit the "selected" column to paste in the instructor dedup'd ids saved in Step b.  Save the filter
    j. Save the criteria
    k. Run the results
    l. Export the results.  
    m. Make sure the results match the number of expected ids.  You may run the entire list of IDs at one time or break the list into smaller groups and repeat steps h-m.
    n. Once all results are extracted and available, update the instructor tab of the migration form with the value for "Instructor" and the correct Alma Primary ID.

    Appendix C - Barcode to MMSID

    Alma can link courses to inventory, but the required link is the MMS id (bib key). Typically in Ares, the link to inventory is the item barcode.  This section describes how to retrieve a list of MMSids given a list of barcodes.

    From Item details file
    1. Find barcode columns
    2. Filter to barcodes valid barcodes (remove blanks, any inaccurate fields like call numbers, item formats, etc.)
    3. Select all remaining values
    4. Copy to Notepad++ 
    5. Add a column header "Barcodes"
    6. Save as text file (barcodes.txt)

    In Alma
    1. In Alma, create itemized set from the file > Admin > Manage Sets > Create Itemized Set
    2. Any set name
    3. Change set content type to 'Physical Items'
    4. Change 'Add items to set' to "from file"
    5. Drop a file or Upload the Barcodes.txt file 
    6. When set created, go to 'Content' > Use the 'Export List' feature for Excel (All fields) to download the excel results

    Excel resulting item file
    1. Create a copy of the extract "result" excel before opening
    2. Delete all columns except Item barcode and MMS id - be sure column type for both are changed to TEXT so numbers are not corrupted.  
    If there is a problem with corruption, you may need to open the copy with a tool such as "CSVed" which is a free editing tool which 
    would allow the deletion of the columns without altering the longer numerical data.
    3. Save as a csv file
    4. Send to ExLibris to SFTP server being used for migration

    • Was this article helpful?